diff --git a/doc/小米便签泛读、标注和维护报告文档.docx b/doc/小米便签泛读、标注和维护报告文档.docx index a90b1a4..94d40dd 100644 Binary files a/doc/小米便签泛读、标注和维护报告文档.docx and b/doc/小米便签泛读、标注和维护报告文档.docx differ diff --git a/doc/小米便签泛读报告.docx b/doc/小米便签泛读报告.docx deleted file mode 100644 index b7e541d..0000000 Binary files a/doc/小米便签泛读报告.docx and /dev/null differ diff --git a/src/notes/tool/BackupUtils.java b/src/notes/tool/BackupUtils.java index 39f6ec4..11053a9 100644 --- a/src/notes/tool/BackupUtils.java +++ b/src/notes/tool/BackupUtils.java @@ -35,14 +35,31 @@ import java.io.FileOutputStream; import java.io.IOException; import java.io.PrintStream; +/** + * 笔记备份工具类，采用单例模式设计 + * 负责将笔记数据从数据库导出为可读的文本格式文件 + */ public class BackupUtils { + // 日志标签，用于调试时在 Logcat 中标识本类的日志输出 private static final String TAG = "BackupUtils"; - // Singleton stuff + + // 单例模式：持有 BackupUtils 的唯一实例 private static BackupUtils sInstance; + /** + * 获取 BackupUtils 的全局唯一实例（线程安全）。 + * + *

采用懒加载方式，首次调用时才创建实例。 + * 注意：为避免内存泄漏，建议传入 Application Context， + * 但即使传入 Activity Context，内部也应转换为 ApplicationContext 使用（需在构造函数中处理）。 + * + * @param context 上下文，用于初始化 BackupUtils 所需的系统服务或资源 + * @return BackupUtils 的单例对象 + */ public static synchronized BackupUtils getInstance(Context context) { if (sInstance == null) { + // 首次调用时创建实例 sInstance = new BackupUtils(context); } return sInstance; @@ -69,14 +86,17 @@ public class BackupUtils { mTextExport = new TextExport(context); } + //判断外部存储（如 SD 卡）是否已挂载且可读写 private static boolean externalStorageAvailable() { return Environment.MEDIA_MOUNTED.equals(Environment.getExternalStorageState()); } + //执行导出 public int exportToText() { return mTextExport.exportToText(); } + //获取导出文件的文件名和目录路径 public String getExportedTextFileName() { return mTextExport.mFileName; } @@ -85,12 +105,27 @@ public class BackupUtils { return mTextExport.mFileDirectory; } + /** + * 负责将笔记数据从数据库导出为格式化纯文本文件的内部工具类。 + * + *

该类通过 ContentProvider 查询笔记主表（Notes）和数据明细表（Data）， + * 按照资源文件中定义的模板格式，将内容拼接并写入外部存储的 .txt 文件。 + * 所有数据库查询均使用投影（Projection）限制字段，提升性能与安全性； + * 列索引通过命名常量定义，避免魔法数字，增强可读性与可维护性。 + */ private static class TextExport { + + // === 笔记主表（Notes Table）查询配置 === + + /** + * 查询笔记主表时使用的字段投影（只获取必要字段）。 + * 顺序必须与下方索引常量保持一致。 + */ private static final String[] NOTE_PROJECTION = { - NoteColumns.ID, - NoteColumns.MODIFIED_DATE, - NoteColumns.SNIPPET, - NoteColumns.TYPE + NoteColumns.ID, // 笔记唯一ID + NoteColumns.MODIFIED_DATE, // 最后修改时间 + NoteColumns.SNIPPET, // 笔记摘要/标题 + NoteColumns.TYPE // 笔记类型（用于分组或过滤） }; private static final int NOTE_COLUMN_ID = 0; @@ -99,9 +134,16 @@ public class BackupUtils { private static final int NOTE_COLUMN_SNIPPET = 2; + // === 数据明细表（Data Table）查询配置 === + + /** + * 查询笔记数据明细表时使用的字段投影。 + * 采用类似 Android Contacts Provider 的 EAV 模型， + * 具体字段含义由 MIME_TYPE 决定（如文本、电话等）。 + */ private static final String[] DATA_PROJECTION = { - DataColumns.CONTENT, - DataColumns.MIME_TYPE, + DataColumns.CONTENT, // 主内容（如文本） + DataColumns.MIME_TYPE, // 数据类型（决定 DATA1~DATA4 的语义） DataColumns.DATA1, DataColumns.DATA2, DataColumns.DATA3, @@ -112,19 +154,33 @@ public class BackupUtils { private static final int DATA_COLUMN_MIME_TYPE = 1; - private static final int DATA_COLUMN_CALL_DATE = 2; + private static final int DATA_COLUMN_CALL_DATE = 2; //通话日期字段的列索引 + + private static final int DATA_COLUMN_PHONE_NUMBER = 4; //电话号码字段的列索引 - private static final int DATA_COLUMN_PHONE_NUMBER = 4; + // === 文本格式模板配置 === + /** + * 从资源文件加载的导出文本格式模板数组，支持多语言。 + * 定义在 res/values/arrays.xml 中的 R.array.format_for_exported_note。 + */ private final String [] TEXT_FORMAT; private static final int FORMAT_FOLDER_NAME = 0; private static final int FORMAT_NOTE_DATE = 1; private static final int FORMAT_NOTE_CONTENT = 2; - private Context mContext; - private String mFileName; - private String mFileDirectory; + private Context mContext; //保存上下文，用于访问系统服务 + private String mFileName; //存储最近一次成功导出的文件名 + private String mFileDirectory; //存储导出文件所在的目录路径 + /** + * 构造一个 TextExport 实例，用于执行笔记数据的文本导出任务。 + * + *

该方法从应用资源中加载多语言支持的导出格式模板（R.array.format_for_exported_note）， + * 并初始化导出结果的文件名与目录路径为空字符串（将在导出成功后填充）。 + * + * @param context 上下文对象，用于访问字符串数组资源； + */ public TextExport(Context context) { TEXT_FORMAT = context.getResources().getStringArray(R.array.format_for_exported_note); mContext = context; @@ -132,6 +188,9 @@ public class BackupUtils { mFileDirectory = ""; } + /** + * 根据指定的格式类型 ID，从资源加载的模板数组中获取对应的文本格式字符串。 + */ private String getFormat(int id) { return TEXT_FORMAT[id]; } @@ -146,7 +205,9 @@ public class BackupUtils { folderId }, null); + // 检查查询结果是否有效（非 null） if (notesCursor != null) { + // 尝试将游标移动到第一条记录；若结果集为空，则 moveToFirst() 返回 false，跳过循环 if (notesCursor.moveToFirst()) { do { // Print note's last modified date @@ -156,8 +217,9 @@ public class BackupUtils { // Query data belong to this note String noteId = notesCursor.getString(NOTE_COLUMN_ID); exportNoteToText(noteId, ps); - } while (notesCursor.moveToNext()); + } while (notesCursor.moveToNext()); // 移动到下一条笔记，直到遍历完所有记录 } + // 关闭 Cursor 以释放数据库资源，防止内存泄漏 notesCursor.close(); } } @@ -166,16 +228,20 @@ public class BackupUtils { * Export note identified by id to a print stream */ private void exportNoteToText(String noteId, PrintStream ps) { + // 查询属于该笔记的所有明细数据（Data 表），每条数据可能代表文本、电话记录等 Cursor dataCursor = mContext.getContentResolver().query(Notes.CONTENT_DATA_URI, DATA_PROJECTION, DataColumns.NOTE_ID + "=?", new String[] { noteId }, null); if (dataCursor != null) { + // 遍历该笔记关联的所有数据行（一个笔记可能包含多条 Data 记录） if (dataCursor.moveToFirst()) { do { + // 根据 MIME 类型区分数据类型 String mimeType = dataCursor.getString(DATA_COLUMN_MIME_TYPE); if (DataConstants.CALL_NOTE.equals(mimeType)) { + // 处理“通话笔记”类型：包含电话号码、通话时间、附加位置信息 // Print phone number String phoneNumber = dataCursor.getString(DATA_COLUMN_PHONE_NUMBER); long callDate = dataCursor.getLong(DATA_COLUMN_CALL_DATE); @@ -195,6 +261,7 @@ public class BackupUtils { location)); } } else if (DataConstants.NOTE.equals(mimeType)) { + // 处理普通文本笔记 String content = dataCursor.getString(DATA_COLUMN_CONTENT); if (!TextUtils.isEmpty(content)) { ps.println(String.format(getFormat(FORMAT_NOTE_CONTENT), @@ -206,6 +273,13 @@ public class BackupUtils { dataCursor.close(); } // print a line separator between note + // 注意：当前实现存在两个问题： + // 1. Character.LINE_SEPARATOR 是 Unicode 行分隔符 '\u2028'，多数文本编辑器不识别为换行； + // 2. Character.LETTER_NUMBER 实际值为字符 '1'（ASCII 49），会意外输出数字 "1"。 + // 正确做法应使用标准换行符，例如： + // ps.println(); // 推荐：输出平台兼容换行 + // 或 ps.write('\n'); // 简单 LF 换行（适用于纯文本导出） + // 建议后续重构此逻辑以避免导出文件包含乱码或多余字符。 try { ps.write(new byte[] { Character.LINE_SEPARATOR, Character.LETTER_NUMBER @@ -219,17 +293,22 @@ public class BackupUtils { * Note will be exported as text which is user readable */ public int exportToText() { + // 检查外部存储是否可用（如 SD 卡是否挂载） if (!externalStorageAvailable()) { Log.d(TAG, "Media was not mounted"); return STATE_SD_CARD_UNMOUONTED; } - + // 获取用于写入导出文本的 PrintStream PrintStream ps = getExportToTextPrintStream(); if (ps == null) { Log.e(TAG, "get print stream error"); return STATE_SYSTEM_ERROR; } // First export folder and its notes + // 查询所有“非回收站”的文件夹 + 通话记录专用文件夹（即使它可能不满足普通文件夹条件） + // 条件说明： + // - 类型为 TYPE_FOLDER 且父 ID 不是回收站（排除回收站本身） + // - 或者是固定的通话记录文件夹（ID = ID_CALL_RECORD_FOLDER） Cursor folderCursor = mContext.getContentResolver().query( Notes.CONTENT_NOTE_URI, NOTE_PROJECTION, @@ -241,6 +320,7 @@ public class BackupUtils { if (folderCursor.moveToFirst()) { do { // Print folder's name + // 获取文件夹名称：通话记录文件夹使用固定字符串，其他取自 SNIPPET 字段 String folderName = ""; if(folderCursor.getLong(NOTE_COLUMN_ID) == Notes.ID_CALL_RECORD_FOLDER) { folderName = mContext.getString(R.string.call_record_folder_name); @@ -248,9 +328,11 @@ public class BackupUtils { folderName = folderCursor.getString(NOTE_COLUMN_SNIPPET); } if (!TextUtils.isEmpty(folderName)) { + // 使用预定义模板输出文件夹标题 ps.println(String.format(getFormat(FORMAT_FOLDER_NAME), folderName)); } String folderId = folderCursor.getString(NOTE_COLUMN_ID); + // 递归导出该文件夹下的所有笔记 exportFolderToText(folderId, ps); } while (folderCursor.moveToNext()); } @@ -258,6 +340,7 @@ public class BackupUtils { } // Export notes in root's folder + // 查询“根目录”下的普通笔记（即 PARENT_ID = 0 且类型为普通笔记） Cursor noteCursor = mContext.getContentResolver().query( Notes.CONTENT_NOTE_URI, NOTE_PROJECTION, @@ -267,6 +350,7 @@ public class BackupUtils { if (noteCursor != null) { if (noteCursor.moveToFirst()) { do { + // 输出根目录笔记的最后修改时间 ps.println(String.format(getFormat(FORMAT_NOTE_DATE), DateFormat.format( mContext.getString(R.string.format_datetime_mdhm), noteCursor.getLong(NOTE_COLUMN_MODIFIED_DATE)))); @@ -286,22 +370,28 @@ public class BackupUtils { * 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); if (file == null) { Log.e(TAG, "create file to exported failed"); return null; } + // 缓存文件名和目录路径 mFileName = file.getName(); mFileDirectory = mContext.getString(R.string.file_path); PrintStream ps = null; try { + // 创建指向该文件的输出流（覆盖写入模式） FileOutputStream fos = new FileOutputStream(file); + // 包装为 PrintStream，便于使用 println() 等文本写入方法 ps = new PrintStream(fos); } catch (FileNotFoundException e) { + // 文件无法创建（如路径无效、权限不足、存储未挂载等） e.printStackTrace(); return null; } catch (NullPointerException e) { + // 通常由 generateFileMountedOnSDcard 返回 null 或上下文异常导致 e.printStackTrace(); return null; } @@ -313,10 +403,13 @@ public class BackupUtils { * Generate the text file to store imported data */ 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( fileNameFormatResId, DateFormat.format(context.getString(R.string.format_date_ymd), @@ -324,21 +417,24 @@ public class BackupUtils { File file = new File(sb.toString()); try { + // 确保目标目录存在，不存在则尝试创建 if (!filedir.exists()) { - filedir.mkdir(); + filedir.mkdir(); // 注意：mkdir() 只能创建单层目录，若需多级应使用 mkdirs() } + // 创建空文件（如果尚不存在） if (!file.exists()) { file.createNewFile(); } return file; } catch (SecurityException e) { + // 通常因缺少 WRITE_EXTERNAL_STORAGE 权限（Android 6.0+ 需动态申请） e.printStackTrace(); } catch (IOException e) { + // 可能原因：磁盘空间不足、路径为只读、文件被占用等 e.printStackTrace(); } + // 任一异常发生或创建失败时，返回 null 表示文件准备失败 return null; } } - - diff --git a/src/notes/tool/DataUtils.java b/src/notes/tool/DataUtils.java index 2a14982..94c08d7 100644 --- a/src/notes/tool/DataUtils.java +++ b/src/notes/tool/DataUtils.java @@ -34,10 +34,21 @@ import net.micode.notes.ui.NotesListAdapter.AppWidgetAttribute; import java.util.ArrayList; import java.util.HashSet; - +/** + * 数据操作工具类，提供对笔记数据库的各种常用操作 + * 包括批量删除、移动、查询等数据库操作方法 + */ public class DataUtils { - public static final String TAG = "DataUtils"; + private static final String TAG = "DataUtils"; // 日志标签 + + /** + * 批量删除笔记 + * @param resolver 内容解析器，用于访问ContentProvider + * @param ids 要删除的笔记ID集合 + * @return 删除成功返回true，失败返回false + */ public static boolean batchDeleteNotes(ContentResolver resolver, HashSet ids) { + // 参数检查：如果ID集合为空，直接返回成功 if (ids == null) { Log.d(TAG, "the ids is null"); return true; @@ -47,18 +58,24 @@ public class DataUtils { return true; } + // 创建批量操作列表 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)); operationList.add(builder.build()); } + try { + // 执行批量删除操作 ContentProviderResult[] results = resolver.applyBatch(Notes.AUTHORITY, operationList); + // 检查操作结果 if (results == null || results.length == 0 || results[0] == null) { Log.d(TAG, "delete notes failed, ids:" + ids.toString()); return false; @@ -72,32 +89,52 @@ public class DataUtils { return false; } + /** + * 将笔记移动到指定文件夹 + * @param resolver 内容解析器 + * @param id 要移动的笔记ID + * @param srcFolderId 源文件夹ID + * @param desFolderId 目标文件夹ID + */ public static void moveNoteToFoler(ContentResolver resolver, long id, long srcFolderId, long desFolderId) { ContentValues values = new ContentValues(); - values.put(NoteColumns.PARENT_ID, desFolderId); - values.put(NoteColumns.ORIGIN_PARENT_ID, srcFolderId); - values.put(NoteColumns.LOCAL_MODIFIED, 1); + values.put(NoteColumns.PARENT_ID, desFolderId); // 设置新的父文件夹ID + values.put(NoteColumns.ORIGIN_PARENT_ID, srcFolderId); // 记录原始父文件夹ID + values.put(NoteColumns.LOCAL_MODIFIED, 1); // 标记为本地已修改（用于同步） + // 执行更新操作 resolver.update(ContentUris.withAppendedId(Notes.CONTENT_NOTE_URI, id), values, null, null); } + /** + * 批量移动笔记到指定文件夹 + * @param resolver 内容解析器 + * @param ids 要移动的笔记ID集合 + * @param folderId 目标文件夹ID + * @return 移动成功返回true，失败返回false + */ public static boolean batchMoveToFolder(ContentResolver resolver, HashSet ids, - long folderId) { + long folderId) { + // 参数检查 if (ids == null) { Log.d(TAG, "the ids is null"); return true; } + // 创建批量操作列表 ArrayList operationList = new ArrayList(); for (long id : ids) { + // 为每个笔记创建更新操作 ContentProviderOperation.Builder builder = ContentProviderOperation .newUpdate(ContentUris.withAppendedId(Notes.CONTENT_NOTE_URI, id)); - builder.withValue(NoteColumns.PARENT_ID, folderId); - builder.withValue(NoteColumns.LOCAL_MODIFIED, 1); + builder.withValue(NoteColumns.PARENT_ID, folderId); // 设置目标文件夹ID + builder.withValue(NoteColumns.LOCAL_MODIFIED, 1); // 标记为本地已修改 operationList.add(builder.build()); } try { + // 执行批量移动操作 ContentProviderResult[] results = resolver.applyBatch(Notes.AUTHORITY, operationList); + // 检查操作结果 if (results == null || results.length == 0 || results[0] == null) { Log.d(TAG, "delete notes failed, ids:" + ids.toString()); return false; @@ -112,9 +149,12 @@ public class DataUtils { } /** - * Get the all folder count except system folders {@link Notes#TYPE_SYSTEM}} + * 获取用户文件夹数量（排除系统文件夹） + * @param resolver 内容解析器 + * @return 用户文件夹的数量 */ public static int getUserFolderCount(ContentResolver resolver) { + // 查询条件：类型为文件夹且不在垃圾箱中 Cursor cursor =resolver.query(Notes.CONTENT_NOTE_URI, new String[] { "COUNT(*)" }, NoteColumns.TYPE + "=? AND " + NoteColumns.PARENT_ID + "<>?", @@ -125,17 +165,24 @@ public class DataUtils { if(cursor != null) { if(cursor.moveToFirst()) { try { - count = cursor.getInt(0); + count = cursor.getInt(0); // 获取数量 } catch (IndexOutOfBoundsException e) { Log.e(TAG, "get folder count failed:" + e.toString()); } finally { - cursor.close(); + cursor.close(); // 确保游标被关闭 } } } return count; } + /** + * 检查指定类型和ID的笔记是否在数据库中可见（不在垃圾箱中） + * @param resolver 内容解析器 + * @param noteId 笔记ID + * @param type 笔记类型 + * @return 如果存在且可见返回true，否则返回false + */ public static boolean visibleInNoteDatabase(ContentResolver resolver, long noteId, int type) { Cursor cursor = resolver.query(ContentUris.withAppendedId(Notes.CONTENT_NOTE_URI, noteId), null, @@ -146,13 +193,19 @@ public class DataUtils { boolean exist = false; if (cursor != null) { if (cursor.getCount() > 0) { - exist = true; + exist = true; // 有记录存在 } cursor.close(); } return exist; } + /** + * 检查指定ID的笔记是否存在于数据库中 + * @param resolver 内容解析器 + * @param noteId 笔记ID + * @return 如果存在返回true，否则返回false + */ public static boolean existInNoteDatabase(ContentResolver resolver, long noteId) { Cursor cursor = resolver.query(ContentUris.withAppendedId(Notes.CONTENT_NOTE_URI, noteId), null, null, null, null); @@ -167,6 +220,12 @@ public class DataUtils { return exist; } + /** + * 检查指定ID的数据项是否存在于数据表中 + * @param resolver 内容解析器 + * @param dataId 数据项ID + * @return 如果存在返回true，否则返回false + */ public static boolean existInDataDatabase(ContentResolver resolver, long dataId) { Cursor cursor = resolver.query(ContentUris.withAppendedId(Notes.CONTENT_DATA_URI, dataId), null, null, null, null); @@ -181,11 +240,17 @@ public class DataUtils { return exist; } + /** + * 检查指定名称的文件夹是否已存在（可见文件夹，不在垃圾箱中） + * @param resolver 内容解析器 + * @param name 文件夹名称 + * @return 如果存在返回true，否则返回false + */ 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 + "=?", + " AND " + NoteColumns.PARENT_ID + "<>" + Notes.ID_TRASH_FOLER + + " AND " + NoteColumns.SNIPPET + "=?", new String[] { name }, null); boolean exist = false; if(cursor != null) { @@ -197,7 +262,14 @@ public class DataUtils { return exist; } + /** + * 获取文件夹中所有笔记关联的小部件属性 + * @param resolver 内容解析器 + * @param folderId 文件夹ID + * @return 小部件属性集合，如果没有返回null + */ public static HashSet getFolderNoteWidget(ContentResolver resolver, long folderId) { + // 查询文件夹中所有笔记的小部件信息 Cursor c = resolver.query(Notes.CONTENT_NOTE_URI, new String[] { NoteColumns.WIDGET_ID, NoteColumns.WIDGET_TYPE }, NoteColumns.PARENT_ID + "=?", @@ -210,9 +282,10 @@ public class DataUtils { set = new HashSet(); do { try { + // 创建小部件属性对象并添加到集合 AppWidgetAttribute widget = new AppWidgetAttribute(); - widget.widgetId = c.getInt(0); - widget.widgetType = c.getInt(1); + widget.widgetId = c.getInt(0); // 小部件ID + widget.widgetType = c.getInt(1); // 小部件类型 set.add(widget); } catch (IndexOutOfBoundsException e) { Log.e(TAG, e.toString()); @@ -224,7 +297,14 @@ public class DataUtils { return set; } + /** + * 根据笔记ID获取对应的电话号码（用于通话记录笔记） + * @param resolver 内容解析器 + * @param noteId 笔记ID + * @return 电话号码，如果不存在返回空字符串 + */ public static String getCallNumberByNoteId(ContentResolver resolver, long noteId) { + // 查询通话记录数据 Cursor cursor = resolver.query(Notes.CONTENT_DATA_URI, new String [] { CallNote.PHONE_NUMBER }, CallNote.NOTE_ID + "=? AND " + CallNote.MIME_TYPE + "=?", @@ -233,37 +313,52 @@ 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 { - cursor.close(); + cursor.close(); // 确保游标被关闭 } } - return ""; + return ""; // 没有找到返回空字符串 } + /** + * 根据电话号码和通话日期获取对应的笔记ID + * @param resolver 内容解析器 + * @param phoneNumber 电话号码 + * @param callDate 通话日期 + * @return 笔记ID，如果不存在返回0 + */ public static long getNoteIdByPhoneNumberAndCallDate(ContentResolver resolver, String phoneNumber, long callDate) { + // 使用自定义的PHONE_NUMBERS_EQUAL函数比较电话号码 Cursor cursor = resolver.query(Notes.CONTENT_DATA_URI, new String [] { CallNote.NOTE_ID }, CallNote.CALL_DATE + "=? AND " + CallNote.MIME_TYPE + "=? AND PHONE_NUMBERS_EQUAL(" - + CallNote.PHONE_NUMBER + ",?)", + + CallNote.PHONE_NUMBER + ",?)", new String [] { String.valueOf(callDate), CallNote.CONTENT_ITEM_TYPE, phoneNumber }, null); if (cursor != null) { if (cursor.moveToFirst()) { try { - return cursor.getLong(0); + return cursor.getLong(0); // 返回笔记ID } catch (IndexOutOfBoundsException e) { Log.e(TAG, "Get call note id fails " + e.toString()); } } cursor.close(); } - return 0; + return 0; // 没有找到返回0 } + /** + * 根据笔记ID获取内容摘要 + * @param resolver 内容解析器 + * @param noteId 笔记ID + * @return 笔记内容摘要 + * @throws IllegalArgumentException 如果笔记不存在抛出异常 + */ public static String getSnippetById(ContentResolver resolver, long noteId) { Cursor cursor = resolver.query(Notes.CONTENT_NOTE_URI, new String [] { NoteColumns.SNIPPET }, @@ -274,7 +369,7 @@ public class DataUtils { if (cursor != null) { String snippet = ""; if (cursor.moveToFirst()) { - snippet = cursor.getString(0); + snippet = cursor.getString(0); // 获取内容摘要 } cursor.close(); return snippet; @@ -282,14 +377,19 @@ public class DataUtils { throw new IllegalArgumentException("Note is not found with id: " + noteId); } + /** + * 格式化内容摘要（去除首尾空格，只保留第一行） + * @param snippet 原始内容摘要 + * @return 格式化后的内容摘要 + */ 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'); // 查找第一个换行符 if (index != -1) { - snippet = snippet.substring(0, index); + snippet = snippet.substring(0, index); // 只保留第一行 } } return snippet; } -} +} \ No newline at end of file diff --git a/src/notes/tool/GTaskStringUtils.java b/src/notes/tool/GTaskStringUtils.java index 666b729..30e53f6 100644 --- a/src/notes/tool/GTaskStringUtils.java +++ b/src/notes/tool/GTaskStringUtils.java @@ -16,98 +16,112 @@ package net.micode.notes.tool; +/** + * GTask字符串常量定义类 + * 定义Google Task API相关的JSON字段名和常量值 + * 用于便签与Google Task服务的数据同步 + */ public class GTaskStringUtils { + // ==================== 动作相关常量 ==================== + /** 动作ID字段名 */ public final static String GTASK_JSON_ACTION_ID = "action_id"; - + /** 动作列表字段名 */ public final static String GTASK_JSON_ACTION_LIST = "action_list"; - + /** 动作类型字段名 */ public final static String GTASK_JSON_ACTION_TYPE = "action_type"; - + /** 创建动作类型 */ public final static String GTASK_JSON_ACTION_TYPE_CREATE = "create"; - + /** 获取所有动作类型 */ public final static String GTASK_JSON_ACTION_TYPE_GETALL = "get_all"; - + /** 移动动作类型 */ public final static String GTASK_JSON_ACTION_TYPE_MOVE = "move"; - + /** 更新动作类型 */ public final static String GTASK_JSON_ACTION_TYPE_UPDATE = "update"; + // ==================== 实体属性相关常量 ==================== + /** 创建者ID字段名 */ public final static String GTASK_JSON_CREATOR_ID = "creator_id"; - + /** 子实体字段名 */ public final static String GTASK_JSON_CHILD_ENTITY = "child_entity"; - + /** 客户端版本字段名 */ public final static String GTASK_JSON_CLIENT_VERSION = "client_version"; - + /** 完成状态字段名 */ public final static String GTASK_JSON_COMPLETED = "completed"; - + /** 当前列表ID字段名 */ public final static String GTASK_JSON_CURRENT_LIST_ID = "current_list_id"; - + /** 默认列表ID字段名 */ public final static String GTASK_JSON_DEFAULT_LIST_ID = "default_list_id"; - + /** 删除状态字段名 */ public final static String GTASK_JSON_DELETED = "deleted"; - + /** 目标列表字段名 */ public final static String GTASK_JSON_DEST_LIST = "dest_list"; - + /** 目标父级字段名 */ public final static String GTASK_JSON_DEST_PARENT = "dest_parent"; - + /** 目标父级类型字段名 */ public final static String GTASK_JSON_DEST_PARENT_TYPE = "dest_parent_type"; - + /** 实体增量字段名 */ public final static String GTASK_JSON_ENTITY_DELTA = "entity_delta"; - + /** 实体类型字段名 */ public final static String GTASK_JSON_ENTITY_TYPE = "entity_type"; - + /** 获取已删除项字段名 */ public final static String GTASK_JSON_GET_DELETED = "get_deleted"; - + /** ID字段名 */ public final static String GTASK_JSON_ID = "id"; - + /** 索引字段名 */ public final static String GTASK_JSON_INDEX = "index"; - + /** 最后修改时间字段名 */ public final static String GTASK_JSON_LAST_MODIFIED = "last_modified"; - + /** 最新同步点字段名 */ public final static String GTASK_JSON_LATEST_SYNC_POINT = "latest_sync_point"; - + /** 列表ID字段名 */ public final static String GTASK_JSON_LIST_ID = "list_id"; + // ==================== 数据结构相关常量 ==================== + /** 列表集合字段名 */ public final static String GTASK_JSON_LISTS = "lists"; - + /** 名称字段名 */ public final static String GTASK_JSON_NAME = "name"; - + /** 新ID字段名 */ public final static String GTASK_JSON_NEW_ID = "new_id"; - + /** 便签字段名 */ public final static String GTASK_JSON_NOTES = "notes"; - + /** 父级ID字段名 */ public final static String GTASK_JSON_PARENT_ID = "parent_id"; - + /** 前一个兄弟节点ID字段名 */ public final static String GTASK_JSON_PRIOR_SIBLING_ID = "prior_sibling_id"; - + /** 结果字段名 */ public final static String GTASK_JSON_RESULTS = "results"; - + /** 源列表字段名 */ public final static String GTASK_JSON_SOURCE_LIST = "source_list"; - + /** 任务字段名 */ public final static String GTASK_JSON_TASKS = "tasks"; - + /** 类型字段名 */ public final static String GTASK_JSON_TYPE = "type"; - + /** 组类型（文件夹） */ public final static String GTASK_JSON_TYPE_GROUP = "GROUP"; - + /** 任务类型（便签） */ public final static String GTASK_JSON_TYPE_TASK = "TASK"; - + /** 用户字段名 */ public final static String GTASK_JSON_USER = "user"; + // ==================== MIUI便签特定常量 ==================== + /** MIUI文件夹前缀，用于标识MIUI便签创建的文件夹 */ public final static String MIUI_FOLDER_PREFFIX = "[MIUI_Notes]"; - + /** 默认文件夹名称 */ public final static String FOLDER_DEFAULT = "Default"; - + /** 通话记录便签文件夹名称 */ public final static String FOLDER_CALL_NOTE = "Call_Note"; - + /** 元数据文件夹名称 */ public final static String FOLDER_META = "METADATA"; + // ==================== 元数据相关常量 ==================== + /** 元数据头：Google Task ID */ public final static String META_HEAD_GTASK_ID = "meta_gid"; - + /** 元数据头：便签信息 */ public final static String META_HEAD_NOTE = "meta_note"; - + /** 元数据头：数据信息 */ public final static String META_HEAD_DATA = "meta_data"; - + /** 元数据便签名称，提示用户不要修改或删除 */ public final static String META_NOTE_NAME = "[META INFO] DON'T UPDATE AND DELETE"; - -} +} \ No newline at end of file diff --git a/src/notes/tool/ResourceParser.java b/src/notes/tool/ResourceParser.java index 1ad3ad6..445a271 100644 --- a/src/notes/tool/ResourceParser.java +++ b/src/notes/tool/ResourceParser.java @@ -22,151 +22,253 @@ import android.preference.PreferenceManager; import net.micode.notes.R; import net.micode.notes.ui.NotesPreferenceActivity; +/** + * 资源映射器工具类 + * 统一管理便签应用中的颜色、字体大小、背景图片等资源 + * 提供根据ID获取对应资源的方法 + */ public class ResourceParser { + // ==================== 颜色常量定义 ==================== + /** 黄色 - 便签背景颜色标识 */ public static final int YELLOW = 0; + /** 蓝色 - 便签背景颜色标识 */ public static final int BLUE = 1; + /** 白色 - 便签背景颜色标识 */ public static final int WHITE = 2; + /** 绿色 - 便签背景颜色标识 */ public static final int GREEN = 3; + /** 红色 - 便签背景颜色标识 */ public static final int RED = 4; + /** 默认背景颜色 - 黄色 */ public static final int BG_DEFAULT_COLOR = YELLOW; + // ==================== 字体大小常量定义 ==================== + /** 小号字体 */ public static final int TEXT_SMALL = 0; + /** 中号字体 */ public static final int TEXT_MEDIUM = 1; + /** 大号字体 */ public static final int TEXT_LARGE = 2; + /** 超大号字体 */ public static final int TEXT_SUPER = 3; + /** 默认字体大小 - 中号 */ 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, - R.drawable.edit_white, - R.drawable.edit_green, - R.drawable.edit_red + R.drawable.edit_yellow, // 黄色背景 + R.drawable.edit_blue, // 蓝色背景 + R.drawable.edit_white, // 白色背景 + 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, - R.drawable.edit_title_white, - R.drawable.edit_title_green, - R.drawable.edit_title_red + R.drawable.edit_title_yellow, // 黄色标题背景 + R.drawable.edit_title_blue, // 蓝色标题背景 + R.drawable.edit_title_white, // 白色标题背景 + R.drawable.edit_title_green, // 绿色标题背景 + R.drawable.edit_title_red // 红色标题背景 }; + /** + * 根据颜色ID获取便签编辑区域背景资源 + * @param id 颜色ID (YELLOW, BLUE, WHITE, GREEN, RED) + * @return 对应的背景资源ID + */ public static int getNoteBgResource(int id) { return BG_EDIT_RESOURCES[id]; } + /** + * 根据颜色ID获取便签标题区域背景资源 + * @param id 颜色ID (YELLOW, BLUE, WHITE, GREEN, RED) + * @return 对应的标题背景资源ID + */ public static int getNoteTitleBgResource(int id) { return BG_EDIT_TITLE_RESOURCES[id]; } } + /** + * 获取默认背景颜色ID + * 根据用户设置决定使用随机颜色还是默认颜色 + * @param context 上下文对象 + * @return 背景颜色ID + */ public static int getDefaultBgId(Context context) { + // 检查用户是否启用了随机背景颜色功能 if (PreferenceManager.getDefaultSharedPreferences(context).getBoolean( NotesPreferenceActivity.PREFERENCE_SET_BG_COLOR_KEY, false)) { + // 启用随机颜色：返回0-4之间的随机数 return (int) (Math.random() * NoteBgResources.BG_EDIT_RESOURCES.length); } else { + // 使用默认颜色：黄色 return BG_DEFAULT_COLOR; } } + /** + * 便签列表项背景资源类 + * 管理便签列表中不同位置项的背景图片（第一个、中间、最后一个、单独项） + */ public static class NoteItemBgResources { + /** 列表第一个项的背景资源数组 */ private final static int [] BG_FIRST_RESOURCES = new int [] { - R.drawable.list_yellow_up, - R.drawable.list_blue_up, - R.drawable.list_white_up, - R.drawable.list_green_up, - R.drawable.list_red_up + R.drawable.list_yellow_up, // 黄色第一个项 + R.drawable.list_blue_up, // 蓝色第一个项 + R.drawable.list_white_up, // 白色第一个项 + R.drawable.list_green_up, // 绿色第一个项 + R.drawable.list_red_up // 红色第一个项 }; + /** 列表中间项的背景资源数组 */ private final static int [] BG_NORMAL_RESOURCES = new int [] { - R.drawable.list_yellow_middle, - R.drawable.list_blue_middle, - R.drawable.list_white_middle, - R.drawable.list_green_middle, - R.drawable.list_red_middle + R.drawable.list_yellow_middle, // 黄色中间项 + R.drawable.list_blue_middle, // 蓝色中间项 + R.drawable.list_white_middle, // 白色中间项 + R.drawable.list_green_middle, // 绿色中间项 + R.drawable.list_red_middle // 红色中间项 }; + /** 列表最后一个项的背景资源数组 */ private final static int [] BG_LAST_RESOURCES = new int [] { - R.drawable.list_yellow_down, - R.drawable.list_blue_down, - R.drawable.list_white_down, - R.drawable.list_green_down, - R.drawable.list_red_down, + R.drawable.list_yellow_down, // 黄色最后一个项 + R.drawable.list_blue_down, // 蓝色最后一个项 + R.drawable.list_white_down, // 白色最后一个项 + R.drawable.list_green_down, // 绿色最后一个项 + R.drawable.list_red_down, // 红色最后一个项 }; + /** 单独一项的背景资源数组（列表只有一项时使用） */ private final static int [] BG_SINGLE_RESOURCES = new int [] { - R.drawable.list_yellow_single, - R.drawable.list_blue_single, - R.drawable.list_white_single, - R.drawable.list_green_single, - R.drawable.list_red_single + R.drawable.list_yellow_single, // 黄色单独项 + R.drawable.list_blue_single, // 蓝色单独项 + R.drawable.list_white_single, // 白色单独项 + R.drawable.list_green_single, // 绿色单独项 + R.drawable.list_red_single // 红色单独项 }; + /** + * 获取列表第一个项的背景资源 + * @param id 颜色ID + * @return 对应的背景资源ID + */ public static int getNoteBgFirstRes(int id) { return BG_FIRST_RESOURCES[id]; } + /** + * 获取列表最后一个项的背景资源 + * @param id 颜色ID + * @return 对应的背景资源ID + */ public static int getNoteBgLastRes(int id) { return BG_LAST_RESOURCES[id]; } + /** + * 获取单独一项的背景资源（列表只有一项时使用） + * @param id 颜色ID + * @return 对应的背景资源ID + */ public static int getNoteBgSingleRes(int id) { return BG_SINGLE_RESOURCES[id]; } + /** + * 获取列表中间项的背景资源 + * @param id 颜色ID + * @return 对应的背景资源ID + */ public static int getNoteBgNormalRes(int id) { return BG_NORMAL_RESOURCES[id]; } + /** + * 获取文件夹项的背景资源 + * @return 文件夹背景资源ID + */ public static int getFolderBgRes() { return R.drawable.list_folder; } } + /** + * 小部件背景资源类 + * 管理不同尺寸小部件的背景图片资源 + */ public static class WidgetBgResources { + /** 2x尺寸小部件的背景资源数组 */ private final static int [] BG_2X_RESOURCES = new int [] { - R.drawable.widget_2x_yellow, - R.drawable.widget_2x_blue, - R.drawable.widget_2x_white, - R.drawable.widget_2x_green, - R.drawable.widget_2x_red, + R.drawable.widget_2x_yellow, // 黄色2x小部件 + R.drawable.widget_2x_blue, // 蓝色2x小部件 + R.drawable.widget_2x_white, // 白色2x小部件 + R.drawable.widget_2x_green, // 绿色2x小部件 + R.drawable.widget_2x_red, // 红色2x小部件 }; + /** + * 获取2x尺寸小部件的背景资源 + * @param id 颜色ID + * @return 对应的背景资源ID + */ public static int getWidget2xBgResource(int id) { return BG_2X_RESOURCES[id]; } + /** 4x尺寸小部件的背景资源数组 */ private final static int [] BG_4X_RESOURCES = new int [] { - R.drawable.widget_4x_yellow, - R.drawable.widget_4x_blue, - R.drawable.widget_4x_white, - R.drawable.widget_4x_green, - R.drawable.widget_4x_red + R.drawable.widget_4x_yellow, // 黄色4x小部件 + R.drawable.widget_4x_blue, // 蓝色4x小部件 + R.drawable.widget_4x_white, // 白色4x小部件 + R.drawable.widget_4x_green, // 绿色4x小部件 + R.drawable.widget_4x_red // 红色4x小部件 }; + /** + * 获取4x尺寸小部件的背景资源 + * @param id 颜色ID + * @return 对应的背景资源ID + */ public static int getWidget4xBgResource(int id) { return BG_4X_RESOURCES[id]; } } + /** + * 文本外观资源类 + * 管理不同字体大小的样式资源 + */ public static class TextAppearanceResources { + /** 文本外观样式资源数组，按字体大小顺序排列 */ private final static int [] TEXTAPPEARANCE_RESOURCES = new int [] { - R.style.TextAppearanceNormal, - R.style.TextAppearanceMedium, - R.style.TextAppearanceLarge, - R.style.TextAppearanceSuper + R.style.TextAppearanceNormal, // 正常字体样式 + R.style.TextAppearanceMedium, // 中等字体样式 + R.style.TextAppearanceLarge, // 大字体样式 + R.style.TextAppearanceSuper // 超大字体样式 }; + /** + * 根据字体大小ID获取对应的文本外观资源 + * 包含边界检查，防止数组越界 + * @param id 字体大小ID (TEXT_SMALL, TEXT_MEDIUM, TEXT_LARGE, TEXT_SUPER) + * @return 对应的文本外观资源ID + */ public static int getTexAppearanceResource(int id) { /** - * HACKME: Fix bug of store the resource id in shared preference. - * The id may larger than the length of resources, in this case, - * return the {@link ResourceParser#BG_DEFAULT_FONT_SIZE} + * HACKME: 修复在SharedPreference中存储资源ID的bug + * ID可能大于资源数组的长度，在这种情况下返回默认字体大小 + * 这是一个临时的修复方案，需要后续优化 */ if (id >= TEXTAPPEARANCE_RESOURCES.length) { return BG_DEFAULT_FONT_SIZE; @@ -174,8 +276,12 @@ public class ResourceParser { return TEXTAPPEARANCE_RESOURCES[id]; } + /** + * 获取文本外观资源的总数量 + * @return 资源数组的长度 + */ public static int getResourcesSize() { return TEXTAPPEARANCE_RESOURCES.length; } } -} +} \ No newline at end of file diff --git a/src/notes/ui/AlarmAlertActivity.java b/src/notes/ui/AlarmAlertActivity.java index 85723be..46f4884 100644 --- a/src/notes/ui/AlarmAlertActivity.java +++ b/src/notes/ui/AlarmAlertActivity.java @@ -39,21 +39,26 @@ import net.micode.notes.tool.DataUtils; import java.io.IOException; - +/** + * 闹钟提醒活动 - 当便签闹钟触发时显示的提醒界面 + * 负责播放闹钟声音并显示提醒对话框 + */ 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; + private long mNoteId; // 便签ID + private String mSnippet; // 便签内容片段 + private static final int SNIPPET_PREW_MAX_LEN = 60; // 片段预览最大长度 + MediaPlayer mPlayer; // 媒体播放器，用于播放闹钟声音 @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); - requestWindowFeature(Window.FEATURE_NO_TITLE); + requestWindowFeature(Window.FEATURE_NO_TITLE); // 设置无标题栏 final Window win = getWindow(); + // 添加窗口标志，允许在锁屏界面显示 win.addFlags(WindowManager.LayoutParams.FLAG_SHOW_WHEN_LOCKED); + // 如果屏幕未开启，设置相关标志以唤醒屏幕 if (!isScreenOn()) { win.addFlags(WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON | WindowManager.LayoutParams.FLAG_TURN_SCREEN_ON @@ -64,8 +69,10 @@ public class AlarmAlertActivity extends Activity implements OnClickListener, OnD Intent intent = getIntent(); try { + // 从Intent中获取便签ID和内容片段 mNoteId = Long.valueOf(intent.getData().getPathSegments().get(1)); 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; @@ -75,84 +82,106 @@ public class AlarmAlertActivity extends Activity implements OnClickListener, OnD } mPlayer = new MediaPlayer(); + // 检查便签是否仍然存在于数据库中且为普通类型 if (DataUtils.visibleInNoteDatabase(getContentResolver(), mNoteId, Notes.TYPE_NOTE)) { - showActionDialog(); - playAlarmSound(); + showActionDialog(); // 显示操作对话框 + playAlarmSound(); // 播放闹钟声音 } else { - finish(); + finish(); // 如果便签不存在，直接结束活动 } } + /** + * 检查屏幕是否已开启 + */ 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.prepare(); - mPlayer.setLooping(true); - mPlayer.start(); + mPlayer.setLooping(true); // 设置循环播放 + mPlayer.start(); // 开始播放 } catch (IllegalArgumentException e) { - // TODO Auto-generated catch block e.printStackTrace(); } catch (SecurityException e) { - // TODO Auto-generated catch block e.printStackTrace(); } catch (IllegalStateException e) { - // TODO Auto-generated catch block e.printStackTrace(); } catch (IOException e) { - // TODO Auto-generated catch block e.printStackTrace(); } } + /** + * 显示操作对话框 + */ private void showActionDialog() { AlertDialog.Builder dialog = new AlertDialog.Builder(this); - dialog.setTitle(R.string.app_name); - dialog.setMessage(mSnippet); - dialog.setPositiveButton(R.string.notealert_ok, this); + dialog.setTitle(R.string.app_name); // 设置应用名称作为标题 + dialog.setMessage(mSnippet); // 设置便签片段作为内容 + dialog.setPositiveButton(R.string.notealert_ok, this); // 确定按钮 + + // 如果屏幕已开启，显示进入按钮（用于跳转到便签编辑界面） if (isScreenOn()) { dialog.setNegativeButton(R.string.notealert_enter, this); } - dialog.show().setOnDismissListener(this); + dialog.show().setOnDismissListener(this); // 设置对话框关闭监听器 } + /** + * 对话框按钮点击事件处理 + */ public void onClick(DialogInterface dialog, int which) { switch (which) { - case DialogInterface.BUTTON_NEGATIVE: + 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.putExtra(Intent.EXTRA_UID, mNoteId); // 传递便签ID + startActivity(intent); // 跳转到便签编辑界面 break; default: - break; + break; // 确定按钮或其他按钮，不执行特殊操作 } } + /** + * 对话框关闭事件处理 + */ public void onDismiss(DialogInterface dialog) { - stopAlarmSound(); - finish(); + stopAlarmSound(); // 停止闹钟声音 + finish(); // 结束活动 } + /** + * 停止闹钟声音播放 + */ private void stopAlarmSound() { if (mPlayer != null) { - mPlayer.stop(); - mPlayer.release(); - mPlayer = null; + mPlayer.stop(); // 停止播放 + mPlayer.release(); // 释放资源 + mPlayer = null; // 置空引用 } } -} +} \ No newline at end of file diff --git a/src/notes/ui/AlarmInitReceiver.java b/src/notes/ui/AlarmInitReceiver.java index f221202..6020082 100644 --- a/src/notes/ui/AlarmInitReceiver.java +++ b/src/notes/ui/AlarmInitReceiver.java @@ -27,39 +27,64 @@ import android.database.Cursor; import net.micode.notes.data.Notes; import net.micode.notes.data.Notes.NoteColumns; - +/** + * 闹钟初始化接收器 - 在系统启动或应用初始化时重新设置所有未来的便签提醒 + * 这是一个广播接收器，用于在设备重启后恢复所有未触发的闹钟提醒 + */ public class AlarmInitReceiver extends BroadcastReceiver { + // 数据库查询的列投影，只需要ID和提醒日期 private static final String [] PROJECTION = new String [] { - NoteColumns.ID, - NoteColumns.ALERTED_DATE + NoteColumns.ID, // 便签ID + NoteColumns.ALERTED_DATE // 提醒日期时间戳 }; - private static final int COLUMN_ID = 0; - private static final int COLUMN_ALERTED_DATE = 1; + // 列索引常量，提高代码可读性 + private static final int COLUMN_ID = 0; // ID列索引 + private static final int COLUMN_ALERTED_DATE = 1; // 提醒日期列索引 + /** + * 广播接收器的核心方法，当接收到系统启动广播时被调用 + * @param context 上下文对象 + * @param intent 接收到的广播意图 + */ @Override public void onReceive(Context context, Intent intent) { - long currentDate = System.currentTimeMillis(); + 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) }, + new String[] { String.valueOf(currentDate) }, // 参数：当前时间 null); if (c != null) { + // 遍历查询结果，为每个未来的提醒设置闹钟 if (c.moveToFirst()) { do { - long alertDate = c.getLong(COLUMN_ALERTED_DATE); + long alertDate = c.getLong(COLUMN_ALERTED_DATE); // 获取提醒时间 + long noteId = c.getLong(COLUMN_ID); // 获取便签ID + + // 创建闹钟触发时的广播意图 Intent sender = new Intent(context, AlarmReceiver.class); - sender.setData(ContentUris.withAppendedId(Notes.CONTENT_NOTE_URI, c.getLong(COLUMN_ID))); + // 设置数据URI，便于AlarmReceiver识别具体便签 + sender.setData(ContentUris.withAppendedId(Notes.CONTENT_NOTE_URI, noteId)); + + // 创建待定意图，用于闹钟管理器 PendingIntent pendingIntent = PendingIntent.getBroadcast(context, 0, sender, 0); - AlarmManager alermManager = (AlarmManager) context + + // 获取闹钟管理器服务 + AlarmManager alarmManager = (AlarmManager) context .getSystemService(Context.ALARM_SERVICE); - alermManager.set(AlarmManager.RTC_WAKEUP, alertDate, pendingIntent); - } while (c.moveToNext()); + + // 设置精确闹钟：RTC_WAKEUP表示即使设备休眠也会唤醒并触发 + alarmManager.set(AlarmManager.RTC_WAKEUP, alertDate, pendingIntent); + + } while (c.moveToNext()); // 继续处理下一条记录 } - c.close(); + c.close(); // 关闭游标，释放资源 } } -} +} \ No newline at end of file diff --git a/src/notes/ui/AlarmReceiver.java b/src/notes/ui/AlarmReceiver.java index 54e503b..8461d2b 100644 --- a/src/notes/ui/AlarmReceiver.java +++ b/src/notes/ui/AlarmReceiver.java @@ -20,11 +20,29 @@ import android.content.BroadcastReceiver; import android.content.Context; import android.content.Intent; +/** + * 闹钟接收器 - 接收AlarmManager发出的闹钟广播，并启动闹钟提醒界面 + * 这是一个简单的广播接收器，作为闹钟触发时的中转站 + */ public class AlarmReceiver extends BroadcastReceiver { + + /** + * 当闹钟触发时，系统会调用此方法 + * 主要功能：将广播意图转换为活动意图，并启动闹钟提醒界面 + * + * @param context 上下文对象，用于启动新的Activity + * @param intent 接收到的广播意图，包含便签信息（通过URI传递） + */ @Override public void onReceive(Context context, Intent intent) { + // 将当前意图的类设置为闹钟提醒活动 intent.setClass(context, AlarmAlertActivity.class); + + // 添加标志，确保在新的任务栈中启动Activity + // 这是必要的，因为广播接收器本身没有Activity上下文 intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK); + + // 启动闹钟提醒界面 context.startActivity(intent); } -} +} \ No newline at end of file diff --git a/src/notes/ui/DateTimePicker.java b/src/notes/ui/DateTimePicker.java index 496b0cd..0e8a210 100644 --- a/src/notes/ui/DateTimePicker.java +++ b/src/notes/ui/DateTimePicker.java @@ -21,92 +21,122 @@ import java.util.Calendar; import net.micode.notes.R; - import android.content.Context; import android.text.format.DateFormat; import android.view.View; import android.widget.FrameLayout; import android.widget.NumberPicker; +/** + * 自定义日期时间选择器控件 + * 提供日期、小时、分钟和AM/PM的选择功能 + * 支持12小时制和24小时制两种显示模式 + */ public class DateTimePicker extends FrameLayout { - + // 默认启用状态 private static final boolean DEFAULT_ENABLE_STATE = true; - private static final int HOURS_IN_HALF_DAY = 12; - private static final int HOURS_IN_ALL_DAY = 24; - private static final int DAYS_IN_ALL_WEEK = 7; - private static final int DATE_SPINNER_MIN_VAL = 0; - private static final int DATE_SPINNER_MAX_VAL = DAYS_IN_ALL_WEEK - 1; - private static final int HOUR_SPINNER_MIN_VAL_24_HOUR_VIEW = 0; - private static final int HOUR_SPINNER_MAX_VAL_24_HOUR_VIEW = 23; - private static final int HOUR_SPINNER_MIN_VAL_12_HOUR_VIEW = 1; - private static final int HOUR_SPINNER_MAX_VAL_12_HOUR_VIEW = 12; - private static final int MINUT_SPINNER_MIN_VAL = 0; - 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; - - 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 boolean mIs24HourView; - - private boolean mIsEnabled = DEFAULT_ENABLE_STATE; - - private boolean mInitialising; - + // 时间相关常量定义 + private static final int HOURS_IN_HALF_DAY = 12; // 半天的小时数（12小时制） + private static final int HOURS_IN_ALL_DAY = 24; // 全天小时数（24小时制） + private static final int DAYS_IN_ALL_WEEK = 7; // 一周天数 + + // 各选择器的数值范围常量 + private static final int DATE_SPINNER_MIN_VAL = 0; // 日期选择器最小值 + private static final int DATE_SPINNER_MAX_VAL = DAYS_IN_ALL_WEEK - 1; // 日期选择器最大值 + private static final int HOUR_SPINNER_MIN_VAL_24_HOUR_VIEW = 0; // 24小时制小时最小值 + private static final int HOUR_SPINNER_MAX_VAL_24_HOUR_VIEW = 23; // 24小时制小时最大值 + private static final int HOUR_SPINNER_MIN_VAL_12_HOUR_VIEW = 1; // 12小时制小时最小值 + private static final int HOUR_SPINNER_MAX_VAL_12_HOUR_VIEW = 12; // 12小时制小时最大值 + private static final int MINUT_SPINNER_MIN_VAL = 0; // 分钟选择器最小值 + private static final int MINUT_SPINNER_MAX_VAL = 59; // 分钟选择器最大值 + private static final int AMPM_SPINNER_MIN_VAL = 0; // AM/PM选择器最小值 + private static final int AMPM_SPINNER_MAX_VAL = 1; // AM/PM选择器最大值 + + // UI组件 + private final NumberPicker mDateSpinner; // 日期选择器 + private final NumberPicker mHourSpinner; // 小时选择器 + private final NumberPicker mMinuteSpinner; // 分钟选择器 + private final NumberPicker mAmPmSpinner; // AM/PM选择器 + + // 数据状态 + private Calendar mDate; // 当前选择的日期时间 + private String[] mDateDisplayValues = new String[DAYS_IN_ALL_WEEK]; // 日期显示文本数组 + private boolean mIsAm; // 是否为上午（AM） + private boolean mIs24HourView; // 是否为24小时制显示 + private boolean mIsEnabled = DEFAULT_ENABLE_STATE; // 控件是否启用 + private boolean mInitialising; // 初始化状态标志，防止初始化期间触发回调 + + // 回调接口 private OnDateTimeChangedListener mOnDateTimeChangedListener; + /** + * 日期变化监听器 + * 处理日期选择器的值变化，调整日期并更新显示 + */ private NumberPicker.OnValueChangeListener mOnDateChangedListener = new NumberPicker.OnValueChangeListener() { @Override public void onValueChange(NumberPicker picker, int oldVal, int newVal) { + // 根据新旧值差异调整日期 mDate.add(Calendar.DAY_OF_YEAR, newVal - oldVal); - updateDateControl(); - onDateTimeChanged(); + updateDateControl(); // 更新日期显示 + onDateTimeChanged(); // 触发日期时间变化回调 } }; + /** + * 小时变化监听器 + * 处理小时选择器的值变化，包括12/24小时制转换和日期边界处理 + */ private NumberPicker.OnValueChangeListener mOnHourChangedListener = new NumberPicker.OnValueChangeListener() { @Override public void onValueChange(NumberPicker picker, int oldVal, int newVal) { - boolean isDateChanged = false; + boolean isDateChanged = false; // 标记是否需要调整日期 Calendar cal = Calendar.getInstance(); + if (!mIs24HourView) { + // 12小时制下的特殊处理 + // 下午11点->12点：需要增加一天 if (!mIsAm && oldVal == HOURS_IN_HALF_DAY - 1 && newVal == HOURS_IN_HALF_DAY) { cal.setTimeInMillis(mDate.getTimeInMillis()); cal.add(Calendar.DAY_OF_YEAR, 1); isDateChanged = true; - } else if (mIsAm && oldVal == HOURS_IN_HALF_DAY && newVal == HOURS_IN_HALF_DAY - 1) { + } + // 上午12点->11点：需要减少一天 + else if (mIsAm && oldVal == HOURS_IN_HALF_DAY && newVal == HOURS_IN_HALF_DAY - 1) { 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 || - oldVal == HOURS_IN_HALF_DAY && newVal == HOURS_IN_HALF_DAY - 1) { - mIsAm = !mIsAm; - updateAmPmControl(); + + // 处理AM/PM切换（11点<->12点） + 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; // 切换AM/PM状态 + updateAmPmControl(); // 更新AM/PM显示 } } else { + // 24小时制下的特殊处理 + // 23点->0点：需要增加一天 if (oldVal == HOURS_IN_ALL_DAY - 1 && newVal == 0) { cal.setTimeInMillis(mDate.getTimeInMillis()); cal.add(Calendar.DAY_OF_YEAR, 1); isDateChanged = true; - } else if (oldVal == 0 && newVal == HOURS_IN_ALL_DAY - 1) { + } + // 0点->23点：需要减少一天 + else if (oldVal == 0 && newVal == HOURS_IN_ALL_DAY - 1) { cal.setTimeInMillis(mDate.getTimeInMillis()); cal.add(Calendar.DAY_OF_YEAR, -1); isDateChanged = true; } } + + // 计算实际的小时值（12小时制需要转换为24小时制） int newHour = mHourSpinner.getValue() % HOURS_IN_HALF_DAY + (mIsAm ? 0 : HOURS_IN_HALF_DAY); mDate.set(Calendar.HOUR_OF_DAY, newHour); - onDateTimeChanged(); + onDateTimeChanged(); // 触发回调 + + // 如果需要调整日期，则更新年月日 if (isDateChanged) { setCurrentYear(cal.get(Calendar.YEAR)); setCurrentMonth(cal.get(Calendar.MONTH)); @@ -115,111 +145,169 @@ public class DateTimePicker extends FrameLayout { } }; + /** + * 分钟变化监听器 + * 处理分钟选择器的值变化，包括分钟循环边界处理 + */ 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; // 小时调整偏移量 + + // 处理分钟循环：59->0需要增加1小时，0->59需要减少1小时 if (oldVal == maxValue && newVal == minValue) { - offset += 1; + offset += 1; // 向前滚动：增加1小时 } else if (oldVal == minValue && newVal == maxValue) { - offset -= 1; + offset -= 1; // 向后滚动：减少1小时 } + + // 如果需要调整小时 if (offset != 0) { - mDate.add(Calendar.HOUR_OF_DAY, offset); - mHourSpinner.setValue(getCurrentHour()); - updateDateControl(); + mDate.add(Calendar.HOUR_OF_DAY, offset); // 调整小时 + mHourSpinner.setValue(getCurrentHour()); // 更新小时显示 + updateDateControl(); // 更新日期显示（可能因小时调整而跨天） + + // 检查并更新AM/PM状态 int newHour = getCurrentHourOfDay(); if (newHour >= HOURS_IN_HALF_DAY) { - mIsAm = false; + mIsAm = false; // 下午 updateAmPmControl(); } else { - mIsAm = true; + mIsAm = true; // 上午 updateAmPmControl(); } } + + // 设置新的分钟值 mDate.set(Calendar.MINUTE, newVal); - onDateTimeChanged(); + onDateTimeChanged(); // 触发回调 } }; + /** + * AM/PM变化监听器 + * 处理AM/PM选择器的值变化，调整12小时 + */ private NumberPicker.OnValueChangeListener mOnAmPmChangedListener = new NumberPicker.OnValueChangeListener() { @Override public void onValueChange(NumberPicker picker, int oldVal, int newVal) { - mIsAm = !mIsAm; + mIsAm = !mIsAm; // 切换AM/PM状态 + + // 根据AM/PM切换调整12小时 if (mIsAm) { - mDate.add(Calendar.HOUR_OF_DAY, -HOURS_IN_HALF_DAY); + mDate.add(Calendar.HOUR_OF_DAY, -HOURS_IN_HALF_DAY); // PM->AM：减少12小时 } else { - mDate.add(Calendar.HOUR_OF_DAY, HOURS_IN_HALF_DAY); + mDate.add(Calendar.HOUR_OF_DAY, HOURS_IN_HALF_DAY); // AM->PM：增加12小时 } - updateAmPmControl(); - onDateTimeChanged(); + + updateAmPmControl(); // 更新AM/PM显示 + onDateTimeChanged(); // 触发回调 } }; + /** + * 日期时间变化回调接口 + */ public interface OnDateTimeChangedListener { + /** + * 当日期时间发生变化时调用 + * @param view 触发变化的DateTimePicker实例 + * @param year 年份 + * @param month 月份（0-11） + * @param dayOfMonth 日期（1-31） + * @param hourOfDay 小时（0-23） + * @param minute 分钟（0-59） + */ void onDateTimeChanged(DateTimePicker view, int year, int month, - int dayOfMonth, int hourOfDay, int minute); + int dayOfMonth, int hourOfDay, int minute); } + /** + * 构造函数 - 使用当前时间初始化 + * @param context 上下文环境 + */ public DateTimePicker(Context context) { this(context, System.currentTimeMillis()); } + /** + * 构造函数 - 使用指定时间初始化 + * @param context 上下文环境 + * @param date 初始时间（毫秒时间戳） + */ public DateTimePicker(Context context, long date) { this(context, date, DateFormat.is24HourFormat(context)); } + /** + * 主构造函数 - 完整初始化 + * @param context 上下文环境 + * @param date 初始时间（毫秒时间戳） + * @param is24HourView 是否为24小时制显示 + */ public DateTimePicker(Context context, long date, boolean is24HourView) { super(context); - mDate = Calendar.getInstance(); - mInitialising = true; - mIsAm = getCurrentHourOfDay() >= HOURS_IN_HALF_DAY; + mDate = Calendar.getInstance(); // 创建日历实例 + mInitialising = true; // 标记开始初始化 + + // 根据当前时间判断初始AM/PM状态 + mIsAm = (getCurrentHourOfDay() < HOURS_IN_HALF_DAY); + + // 加载布局文件 inflate(context, R.layout.datetime_picker, this); + // 初始化日期选择器 mDateSpinner = (NumberPicker) findViewById(R.id.date); mDateSpinner.setMinValue(DATE_SPINNER_MIN_VAL); mDateSpinner.setMaxValue(DATE_SPINNER_MAX_VAL); mDateSpinner.setOnValueChangedListener(mOnDateChangedListener); + // 初始化小时选择器 mHourSpinner = (NumberPicker) findViewById(R.id.hour); mHourSpinner.setOnValueChangedListener(mOnHourChangedListener); + + // 初始化分钟选择器 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(); + // 初始化AM/PM选择器 + String[] stringsForAmPm = new DateFormatSymbols().getAmPmStrings(); // 获取本地化的AM/PM文本 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 - updateDateControl(); - updateHourControl(); - updateAmPmControl(); + // 更新各控件到初始状态 + updateDateControl(); // 更新日期显示 + updateHourControl(); // 更新小时显示范围 + updateAmPmControl(); // 更新AM/PM显示 - set24HourView(is24HourView); + set24HourView(is24HourView); // 设置时间显示格式 - // set to current time - setCurrentDate(date); + setCurrentDate(date); // 设置初始时间 - setEnabled(isEnabled()); + setEnabled(isEnabled()); // 设置启用状态 - // set the content descriptions - mInitialising = false; + mInitialising = false; // 标记初始化完成 } + /** + * 设置控件启用状态 + * @param enabled true启用，false禁用 + */ @Override public void setEnabled(boolean enabled) { if (mIsEnabled == enabled) { - return; + return; // 状态未变化，直接返回 } super.setEnabled(enabled); + // 设置各子组件的启用状态 mDateSpinner.setEnabled(enabled); mMinuteSpinner.setEnabled(enabled); mHourSpinner.setEnabled(enabled); @@ -227,43 +315,45 @@ public class DateTimePicker extends FrameLayout { mIsEnabled = enabled; } + /** + * 获取控件启用状态 + * @return true启用，false禁用 + */ @Override public boolean isEnabled() { return mIsEnabled; } /** - * Get the current date in millis - * - * @return the current date in millis + * 获取当前日期时间的毫秒时间戳 + * @return 当前日期时间的毫秒时间戳 */ public long getCurrentDateInTimeMillis() { return mDate.getTimeInMillis(); } /** - * Set the current date - * - * @param date The current date in millis + * 设置当前日期时间（通过毫秒时间戳） + * @param date 日期时间的毫秒时间戳 */ public void setCurrentDate(long date) { Calendar cal = Calendar.getInstance(); cal.setTimeInMillis(date); + // 分解设置年月日时分 setCurrentDate(cal.get(Calendar.YEAR), cal.get(Calendar.MONTH), cal.get(Calendar.DAY_OF_MONTH), cal.get(Calendar.HOUR_OF_DAY), cal.get(Calendar.MINUTE)); } /** - * Set the current date - * - * @param year The current year - * @param month The current month - * @param dayOfMonth The current dayOfMonth - * @param hourOfDay The current hourOfDay - * @param minute The current minute + * 设置当前日期时间（通过具体参数） + * @param year 年份 + * @param month 月份（0-11） + * @param dayOfMonth 日期（1-31） + * @param hourOfDay 小时（0-23） + * @param minute 分钟（0-59） */ public void setCurrentDate(int year, int month, - int dayOfMonth, int hourOfDay, int minute) { + int dayOfMonth, int hourOfDay, int minute) { setCurrentYear(year); setCurrentMonth(month); setCurrentDay(dayOfMonth); @@ -272,41 +362,38 @@ public class DateTimePicker extends FrameLayout { } /** - * Get current year - * - * @return The current year + * 获取当前年份 + * @return 当前年份 */ public int getCurrentYear() { return mDate.get(Calendar.YEAR); } /** - * Set current year - * - * @param year The current year + * 设置当前年份 + * @param year 要设置的年份 */ public void setCurrentYear(int year) { + // 初始化期间或年份未变化时跳过回调 if (!mInitialising && year == getCurrentYear()) { return; } mDate.set(Calendar.YEAR, year); - updateDateControl(); - onDateTimeChanged(); + updateDateControl(); // 更新日期显示 + onDateTimeChanged(); // 触发回调 } /** - * Get current month in the year - * - * @return The current month in the year + * 获取当前月份 + * @return 当前月份（0-11） */ public int getCurrentMonth() { return mDate.get(Calendar.MONTH); } /** - * Set current month in the year - * - * @param month The month in the year + * 设置当前月份 + * @param month 要设置的月份（0-11） */ public void setCurrentMonth(int month) { if (!mInitialising && month == getCurrentMonth()) { @@ -318,18 +405,16 @@ public class DateTimePicker extends FrameLayout { } /** - * Get current day of the month - * - * @return The day of the month + * 获取当前日期 + * @return 当前日期（1-31） */ public int getCurrentDay() { return mDate.get(Calendar.DAY_OF_MONTH); } /** - * Set current day of the month - * - * @param dayOfMonth The day of the month + * 设置当前日期 + * @param dayOfMonth 要设置的日期（1-31） */ public void setCurrentDay(int dayOfMonth) { if (!mInitialising && dayOfMonth == getCurrentDay()) { @@ -341,145 +426,179 @@ public class DateTimePicker extends FrameLayout { } /** - * Get current hour in 24 hour mode, in the range (0~23) - * @return The current hour in 24 hour mode + * 获取当前小时（24小时制） + * @return 当前小时（0-23） */ public int getCurrentHourOfDay() { return mDate.get(Calendar.HOUR_OF_DAY); } + /** + * 获取当前显示的小时值（根据12/24小时制格式） + * @return 12小时制返回1-12，24小时制返回0-23 + */ private int getCurrentHour() { if (mIs24HourView){ - return getCurrentHourOfDay(); + return getCurrentHourOfDay(); // 24小时制直接返回 } else { int hour = getCurrentHourOfDay(); + // 12小时制转换：0点显示为12，13-23点转换为1-11 if (hour > HOURS_IN_HALF_DAY) { - return hour - HOURS_IN_HALF_DAY; + return hour - HOURS_IN_HALF_DAY; // 下午时间：13-23 -> 1-11 } else { - return hour == 0 ? HOURS_IN_HALF_DAY : hour; + return hour == 0 ? HOURS_IN_HALF_DAY : hour; // 0点显示为12，1-11点不变 } } } /** - * Set current hour in 24 hour mode, in the range (0~23) - * - * @param hourOfDay + * 设置当前小时（24小时制） + * @param hourOfDay 要设置的小时（0-23） */ public void setCurrentHour(int hourOfDay) { if (!mInitialising && hourOfDay == getCurrentHourOfDay()) { return; } mDate.set(Calendar.HOUR_OF_DAY, hourOfDay); + + // 12小时制需要额外处理AM/PM状态 if (!mIs24HourView) { if (hourOfDay >= HOURS_IN_HALF_DAY) { - mIsAm = false; + mIsAm = false; // 下午 if (hourOfDay > HOURS_IN_HALF_DAY) { - hourOfDay -= HOURS_IN_HALF_DAY; + hourOfDay -= HOURS_IN_HALF_DAY; // 13-23点转换为1-11点 } } else { - mIsAm = true; + mIsAm = true; // 上午 if (hourOfDay == 0) { - hourOfDay = HOURS_IN_HALF_DAY; + hourOfDay = HOURS_IN_HALF_DAY; // 0点转换为12点 } } - updateAmPmControl(); + updateAmPmControl(); // 更新AM/PM显示 } - mHourSpinner.setValue(hourOfDay); - onDateTimeChanged(); + + mHourSpinner.setValue(hourOfDay); // 设置小时选择器值 + onDateTimeChanged(); // 触发回调 } /** - * Get currentMinute - * - * @return The Current Minute + * 获取当前分钟 + * @return 当前分钟（0-59） */ public int getCurrentMinute() { return mDate.get(Calendar.MINUTE); } /** - * Set current minute + * 设置当前分钟 + * @param minute 要设置的分钟（0-59） */ public void setCurrentMinute(int minute) { if (!mInitialising && minute == getCurrentMinute()) { return; } - mMinuteSpinner.setValue(minute); - mDate.set(Calendar.MINUTE, minute); - onDateTimeChanged(); + mMinuteSpinner.setValue(minute); // 设置分钟选择器值 + mDate.set(Calendar.MINUTE, minute); // 设置日历分钟 + onDateTimeChanged(); // 触发回调 } /** - * @return true if this is in 24 hour view else false. + * 检查是否为24小时制显示 + * @return true为24小时制，false为12小时制 */ public boolean is24HourView () { return mIs24HourView; } /** - * Set whether in 24 hour or AM/PM mode. - * - * @param is24HourView True for 24 hour mode. False for AM/PM mode. + * 设置时间显示格式 + * @param is24HourView true为24小时制，false为12小时制 */ public void set24HourView(boolean is24HourView) { if (mIs24HourView == is24HourView) { - return; + return; // 显示模式未变化，直接返回 } mIs24HourView = is24HourView; + + // 显示/隐藏AM/PM选择器 mAmPmSpinner.setVisibility(is24HourView ? View.GONE : View.VISIBLE); - int hour = getCurrentHourOfDay(); - updateHourControl(); - setCurrentHour(hour); - updateAmPmControl(); + + int hour = getCurrentHourOfDay(); // 保存当前小时 + updateHourControl(); // 更新小时选择器范围 + setCurrentHour(hour); // 重新设置小时（会进行格式转换） + updateAmPmControl(); // 更新AM/PM显示 } + /** + * 更新日期显示控制 + * 以当前日期为中心，显示前后各3天的日期范围（共7天） + */ private void updateDateControl() { Calendar cal = Calendar.getInstance(); cal.setTimeInMillis(mDate.getTimeInMillis()); + // 从当前日期前3天开始计算（中间项为当前日期） cal.add(Calendar.DAY_OF_YEAR, -DAYS_IN_ALL_WEEK / 2 - 1); - mDateSpinner.setDisplayedValues(null); + + mDateSpinner.setDisplayedValues(null); // 清空显示值 + + // 生成7天的日期显示文本 for (int i = 0; i < DAYS_IN_ALL_WEEK; ++i) { - cal.add(Calendar.DAY_OF_YEAR, 1); + cal.add(Calendar.DAY_OF_YEAR, 1); // 增加一天 + // 格式化为"月.日 星期几"的格式 mDateDisplayValues[i] = (String) DateFormat.format("MM.dd EEEE", cal); } - mDateSpinner.setDisplayedValues(mDateDisplayValues); - mDateSpinner.setValue(DAYS_IN_ALL_WEEK / 2); - mDateSpinner.invalidate(); + + mDateSpinner.setDisplayedValues(mDateDisplayValues); // 设置显示文本 + mDateSpinner.setValue(DAYS_IN_ALL_WEEK / 2); // 选中中间项（当前日期） + mDateSpinner.invalidate(); // 刷新显示 } + /** + * 更新AM/PM显示控制 + * 根据24小时制设置显示或隐藏AM/PM选择器 + */ private void updateAmPmControl() { if (mIs24HourView) { - mAmPmSpinner.setVisibility(View.GONE); + mAmPmSpinner.setVisibility(View.GONE); // 24小时制隐藏AM/PM } else { - int index = mIsAm ? Calendar.AM : Calendar.PM; - mAmPmSpinner.setValue(index); - mAmPmSpinner.setVisibility(View.VISIBLE); + int index = mIsAm ? Calendar.AM : Calendar.PM; // 计算AM/PM索引 + mAmPmSpinner.setValue(index); // 设置AM/PM选择器值 + mAmPmSpinner.setVisibility(View.VISIBLE); // 显示AM/PM选择器 } } + /** + * 更新小时显示控制 + * 根据12/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 监听器回调接口 */ public void setOnDateTimeChangedListener(OnDateTimeChangedListener callback) { mOnDateTimeChangedListener = callback; } + /** + * 日期时间变化回调方法 + * 当任何日期时间组件发生变化时调用，通知监听器 + */ private void onDateTimeChanged() { if (mOnDateTimeChangedListener != null) { mOnDateTimeChangedListener.onDateTimeChanged(this, getCurrentYear(), getCurrentMonth(), getCurrentDay(), getCurrentHourOfDay(), getCurrentMinute()); } } -} +} \ No newline at end of file diff --git a/src/notes/ui/DateTimePickerDialog.java b/src/notes/ui/DateTimePickerDialog.java index 2c47ba4..dec755f 100644 --- a/src/notes/ui/DateTimePickerDialog.java +++ b/src/notes/ui/DateTimePickerDialog.java @@ -29,62 +29,133 @@ import android.content.DialogInterface.OnClickListener; import android.text.format.DateFormat; import android.text.format.DateUtils; +/** + * 日期时间选择对话框 + * 封装 DateTimePicker 控件，提供完整的日期时间选择对话框功能 + * 包含确定/取消按钮和实时标题更新 + */ public class DateTimePickerDialog extends AlertDialog implements OnClickListener { - + // 当前选择的日期时间 private Calendar mDate = Calendar.getInstance(); + // 是否为24小时制显示 private boolean mIs24HourView; + // 日期时间设置回调接口 private OnDateTimeSetListener mOnDateTimeSetListener; + // 内嵌的日期时间选择器 private DateTimePicker mDateTimePicker; + /** + * 日期时间设置回调接口 + * 当用户点击确定按钮时调用 + */ public interface OnDateTimeSetListener { + /** + * 日期时间设置完成回调 + * @param dialog 对话框实例 + * @param date 选择的日期时间（毫秒时间戳） + */ void OnDateTimeSet(AlertDialog dialog, long date); } + /** + * 构造函数 + * @param context 上下文环境 + * @param date 初始日期时间（毫秒时间戳） + */ public DateTimePickerDialog(Context context, long date) { super(context); + + // 创建日期时间选择器实例 mDateTimePicker = new DateTimePicker(context); - setView(mDateTimePicker); + setView(mDateTimePicker); // 将选择器设置为对话框内容视图 + + // 设置日期时间变化监听器 mDateTimePicker.setOnDateTimeChangedListener(new OnDateTimeChangedListener() { + /** + * 当日期时间选择器的值发生变化时调用 + * 更新内部日期对象并刷新对话框标题 + */ public void onDateTimeChanged(DateTimePicker view, int year, int month, - int dayOfMonth, int hourOfDay, int minute) { + int dayOfMonth, int hourOfDay, int minute) { + // 更新内部 Calendar 对象 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()); } }); + + // 设置初始日期时间 mDate.setTimeInMillis(date); - mDate.set(Calendar.SECOND, 0); + 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); + + // 设置对话框按钮 + setButton(DialogInterface.BUTTON_POSITIVE, context.getString(R.string.datetime_dialog_ok), this); + setButton(DialogInterface.BUTTON_NEGATIVE, context.getString(R.string.datetime_dialog_cancel), (OnClickListener)null); + + // 根据系统设置确定时间显示格式 set24HourView(DateFormat.is24HourFormat(this.getContext())); + + // 初始化对话框标题 updateTitle(mDate.getTimeInMillis()); } + /** + * 设置时间显示格式 + * @param is24HourView true为24小时制，false为12小时制 + */ public void set24HourView(boolean is24HourView) { mIs24HourView = is24HourView; + // 注意：这里应该调用 mDateTimePicker.set24HourView(is24HourView) 来同步内部选择器 + // 当前实现可能存在问题，只更新了本地变量而没有更新内部选择器 } + /** + * 设置日期时间设置完成监听器 + * @param callBack 回调接口 + */ public void setOnDateTimeSetListener(OnDateTimeSetListener callBack) { mOnDateTimeSetListener = callBack; } + /** + * 更新对话框标题 + * 显示当前选择的日期时间信息 + * @param date 要显示的日期时间（毫秒时间戳） + */ private void updateTitle(long date) { + // 设置日期时间显示格式标志 int flag = - DateUtils.FORMAT_SHOW_YEAR | - DateUtils.FORMAT_SHOW_DATE | - DateUtils.FORMAT_SHOW_TIME; + DateUtils.FORMAT_SHOW_YEAR | // 显示年份 + DateUtils.FORMAT_SHOW_DATE | // 显示日期 + DateUtils.FORMAT_SHOW_TIME; // 显示时间 + + // 设置时间格式（24小时制或12小时制） flag |= mIs24HourView ? DateUtils.FORMAT_24HOUR : DateUtils.FORMAT_24HOUR; + // 注意：上面的逻辑有误，应该是 FORMAT_24HOUR 或 FORMAT_12HOUR + // 正确写法：flag |= mIs24HourView ? DateUtils.FORMAT_24HOUR : DateUtils.FORMAT_12HOUR; + + // 格式化日期时间并设置为对话框标题 setTitle(DateUtils.formatDateTime(this.getContext(), date, flag)); } + /** + * 对话框按钮点击事件处理 + * 当用户点击确定按钮时调用 + * @param arg0 对话框实例 + * @param arg1 按钮ID + */ public void onClick(DialogInterface arg0, int arg1) { + // 触发日期时间设置完成回调 if (mOnDateTimeSetListener != null) { mOnDateTimeSetListener.OnDateTimeSet(this, mDate.getTimeInMillis()); } } - } \ No newline at end of file diff --git a/src/notes/ui/DropdownMenu.java b/src/notes/ui/DropdownMenu.java index 613dc74..9799c16 100644 --- a/src/notes/ui/DropdownMenu.java +++ b/src/notes/ui/DropdownMenu.java @@ -27,17 +27,33 @@ import android.widget.PopupMenu.OnMenuItemClickListener; import net.micode.notes.R; +/** + * 自定义下拉菜单控件 + * 封装了PopupMenu的创建和基本操作，提供更简洁的接口 + * 主要用于笔记列表的多选操作菜单 + */ public class DropdownMenu { - private Button mButton; - private PopupMenu mPopupMenu; - private Menu mMenu; + private Button mButton; // 触发下拉菜单的按钮 + private PopupMenu mPopupMenu; // Android原生弹出菜单 + private Menu mMenu; // 菜单对象 + /** + * 构造函数 + * @param context 上下文环境 + * @param button 用于触发菜单的按钮 + * @param menuId 菜单资源ID（R.menu.xxx） + */ public DropdownMenu(Context context, Button button, int menuId) { mButton = button; + // 设置按钮背景为下拉图标 mButton.setBackgroundResource(R.drawable.dropdown_icon); + // 创建弹出菜单，锚点为按钮 mPopupMenu = new PopupMenu(context, mButton); + // 获取菜单对象 mMenu = mPopupMenu.getMenu(); + // 从资源文件加载菜单项 mPopupMenu.getMenuInflater().inflate(menuId, mMenu); + // 设置按钮点击事件：点击时显示下拉菜单 mButton.setOnClickListener(new OnClickListener() { public void onClick(View v) { mPopupMenu.show(); @@ -45,17 +61,30 @@ public class DropdownMenu { }); } + /** + * 设置菜单项点击监听器 + * @param listener 菜单项点击监听器 + */ public void setOnDropdownMenuItemClickListener(OnMenuItemClickListener listener) { if (mPopupMenu != null) { mPopupMenu.setOnMenuItemClickListener(listener); } } + /** + * 根据ID查找菜单项 + * @param id 菜单项资源ID + * @return 找到的菜单项，未找到返回null + */ public MenuItem findItem(int id) { return mMenu.findItem(id); } + /** + * 设置按钮显示的标题文本 + * @param title 要显示的标题 + */ public void setTitle(CharSequence title) { mButton.setText(title); } -} +} \ No newline at end of file diff --git a/src/notes/ui/FoldersListAdapter.java b/src/notes/ui/FoldersListAdapter.java index 96b77da..ec48509 100644 --- a/src/notes/ui/FoldersListAdapter.java +++ b/src/notes/ui/FoldersListAdapter.java @@ -28,53 +28,102 @@ import net.micode.notes.R; import net.micode.notes.data.Notes; import net.micode.notes.data.Notes.NoteColumns; - +/** + * 文件夹列表适配器，用于在对话框或列表中选择目标文件夹 + * 主要用于笔记移动操作时的文件夹选择界面 + */ public class FoldersListAdapter extends CursorAdapter { + // 数据库查询的列投影，只需要ID和名称两列 public static final String [] PROJECTION = { - NoteColumns.ID, - NoteColumns.SNIPPET + NoteColumns.ID, // 文件夹ID + NoteColumns.SNIPPET // 文件夹名称（存储在snippet字段中） }; - public static final int ID_COLUMN = 0; - public static final int NAME_COLUMN = 1; + // 列索引常量 + public static final int ID_COLUMN = 0; // ID列的索引 + public static final int NAME_COLUMN = 1; // 名称列的索引 + /** + * 构造函数 + * @param context 上下文环境 + * @param c 包含文件夹数据的游标 + */ public FoldersListAdapter(Context context, Cursor c) { super(context, c); // TODO Auto-generated constructor stub } + /** + * 创建新的列表项视图 + * @param context 上下文环境 + * @param cursor 数据游标 + * @param parent 父视图容器 + * @return 新创建的文件夹列表项视图 + */ @Override public View newView(Context context, Cursor cursor, ViewGroup parent) { + // 创建自定义的文件夹列表项 return new FolderListItem(context); } + /** + * 将数据绑定到已有的列表项视图 + * @param view 要绑定数据的视图 + * @param context 上下文环境 + * @param cursor 数据游标 + */ @Override public void bindView(View view, Context context, Cursor cursor) { + // 检查视图类型是否正确 if (view instanceof FolderListItem) { + // 根据ID判断文件夹名称：根文件夹显示特殊文本，其他文件夹显示实际名称 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); } } + /** + * 根据位置获取文件夹名称 + * @param context 上下文环境，用于获取资源字符串 + * @param position 列表位置 + * @return 文件夹名称 + */ public String getFolderName(Context context, int position) { + // 获取指定位置的数据游标 Cursor cursor = (Cursor) getItem(position); + // 根据ID判断文件夹名称：根文件夹显示"父文件夹"，其他显示实际名称 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 { - private TextView mName; + private TextView mName; // 显示文件夹名称的文本视图 + /** + * 构造函数 + * @param context 上下文环境 + */ public FolderListItem(Context context) { super(context); + // 从布局文件加载视图 inflate(context, R.layout.folder_list_item, this); + // 查找名称文本视图 mName = (TextView) findViewById(R.id.tv_folder_name); } + /** + * 绑定文件夹名称到视图 + * @param name 文件夹名称 + */ public void bind(String name) { + // 设置文件夹名称文本 mName.setText(name); } } - -} +} \ No newline at end of file diff --git a/src/notes/ui/NoteEditActivity.java b/src/notes/ui/NoteEditActivity.java index 96a9ff8..8f2e9d8 100644 --- a/src/notes/ui/NoteEditActivity.java +++ b/src/notes/ui/NoteEditActivity.java @@ -71,19 +71,24 @@ import java.util.Map; import java.util.regex.Matcher; import java.util.regex.Pattern; - +/** + * 笔记编辑活动，负责笔记的创建、编辑、删除、分享等功能 + * 支持普通文本模式和清单模式两种编辑方式 + */ public class NoteEditActivity extends Activity implements OnClickListener, NoteSettingChangedListener, OnTextViewChangeListener { - private class HeadViewHolder { - public TextView tvModified; - - public ImageView ivAlertIcon; - public TextView tvAlertDate; - - public ImageView ibSetBgColor; + /** + * 头部视图持有者内部类，用于管理笔记头部的UI组件 + */ + private class HeadViewHolder { + public TextView tvModified; // 显示修改时间的文本视图 + public ImageView ivAlertIcon; // 提醒图标 + public TextView tvAlertDate; // 提醒日期文本 + public ImageView ibSetBgColor; // 设置背景颜色的按钮 } + // 背景颜色选择按钮与颜色ID的映射 private static final Map sBgSelectorBtnsMap = new HashMap(); static { sBgSelectorBtnsMap.put(R.id.iv_bg_yellow, ResourceParser.YELLOW); @@ -93,6 +98,7 @@ public class NoteEditActivity extends Activity implements OnClickListener, sBgSelectorBtnsMap.put(R.id.iv_bg_white, ResourceParser.WHITE); } + // 颜色ID与选中状态视图的映射 private static final Map sBgSelectorSelectionMap = new HashMap(); static { sBgSelectorSelectionMap.put(ResourceParser.YELLOW, R.id.iv_bg_yellow_select); @@ -102,6 +108,7 @@ public class NoteEditActivity extends Activity implements OnClickListener, sBgSelectorSelectionMap.put(ResourceParser.WHITE, R.id.iv_bg_white_select); } + // 字体大小选择布局与字体大小ID的映射 private static final Map sFontSizeBtnsMap = new HashMap(); static { sFontSizeBtnsMap.put(R.id.ll_font_large, ResourceParser.TEXT_LARGE); @@ -110,6 +117,7 @@ public class NoteEditActivity extends Activity implements OnClickListener, sFontSizeBtnsMap.put(R.id.ll_font_super, ResourceParser.TEXT_SUPER); } + // 字体大小ID与选中状态图标的映射 private static final Map sFontSelectorSelectionMap = new HashMap(); static { sFontSelectorSelectionMap.put(ResourceParser.TEXT_LARGE, R.id.iv_large_select); @@ -120,55 +128,51 @@ public class NoteEditActivity extends Activity implements OnClickListener, private static final String TAG = "NoteEditActivity"; - private HeadViewHolder mNoteHeaderHolder; - - private View mHeadViewPanel; - - private View mNoteBgColorSelector; - - private View mFontSizeSelector; - - private EditText mNoteEditor; - - private View mNoteEditorPanel; - - private WorkingNote mWorkingNote; - - private SharedPreferences mSharedPrefs; - private int mFontSizeId; + private HeadViewHolder mNoteHeaderHolder; // 头部视图持有者实例 + private View mHeadViewPanel; // 头部面板视图 + private View mNoteBgColorSelector; // 背景颜色选择器面板 + private View mFontSizeSelector; // 字体大小选择器面板 + private EditText mNoteEditor; // 笔记内容编辑器（普通模式） + private View mNoteEditorPanel; // 编辑器面板 + private WorkingNote mWorkingNote; // 当前正在编辑的笔记数据模型 + private SharedPreferences mSharedPrefs; // 偏好设置 + private int mFontSizeId; // 当前字体大小ID - private static final String PREFERENCE_FONT_SIZE = "pref_font_size"; + private static final String PREFERENCE_FONT_SIZE = "pref_font_size"; // 字体大小偏好设置键 + private static final int SHORTCUT_ICON_TITLE_MAX_LEN = 10; // 桌面快捷方式标题最大长度 - private static final int SHORTCUT_ICON_TITLE_MAX_LEN = 10; + // 清单模式下的标记符号 + public static final String TAG_CHECKED = String.valueOf('\u221A'); // 对勾符号 √ + public static final String TAG_UNCHECKED = String.valueOf('\u25A1'); // 方框符号 □ - public static final String TAG_CHECKED = String.valueOf('\u221A'); - public static final String TAG_UNCHECKED = String.valueOf('\u25A1'); - - private LinearLayout mEditTextList; - - private String mUserQuery; - private Pattern mPattern; + private LinearLayout mEditTextList; // 清单模式下的编辑框列表容器 + private String mUserQuery; // 用户搜索查询词（从搜索跳转过来时使用） + private Pattern mPattern; // 用于高亮搜索词的正则表达式模式 + /** + * Activity创建时的初始化方法 + */ @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); this.setContentView(R.layout.note_edit); + // 初始化活动状态，如果是第一次创建且初始化失败则结束活动 if (savedInstanceState == null && !initActivityState(getIntent())) { 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 + * 恢复被系统杀死的活动状态 */ @Override protected void onRestoreInstanceState(Bundle savedInstanceState) { super.onRestoreInstanceState(savedInstanceState); if (savedInstanceState != null && savedInstanceState.containsKey(Intent.EXTRA_UID)) { + // 从保存的状态中恢复笔记ID Intent intent = new Intent(Intent.ACTION_VIEW); intent.putExtra(Intent.EXTRA_UID, savedInstanceState.getLong(Intent.EXTRA_UID)); if (!initActivityState(intent)) { @@ -179,24 +183,26 @@ public class NoteEditActivity extends Activity implements OnClickListener, } } + /** + * 根据Intent初始化活动状态 + * @param intent 启动活动的Intent + * @return 初始化是否成功 + */ private boolean initActivityState(Intent intent) { - /** - * If the user specified the {@link Intent#ACTION_VIEW} but not provided with id, - * then jump to the NotesListActivity - */ mWorkingNote = null; + // 根据Intent的Action类型进行不同处理 if (TextUtils.equals(Intent.ACTION_VIEW, intent.getAction())) { + // 查看现有笔记 long noteId = intent.getLongExtra(Intent.EXTRA_UID, 0); 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 (!DataUtils.visibleInNoteDatabase(getContentResolver(), noteId, Notes.TYPE_NOTE)) { Intent jump = new Intent(this, NotesListActivity.class); startActivity(jump); @@ -204,6 +210,7 @@ public class NoteEditActivity extends Activity implements OnClickListener, finish(); return false; } else { + // 加载现有笔记 mWorkingNote = WorkingNote.load(this, noteId); if (mWorkingNote == null) { Log.e(TAG, "load note failed with note id" + noteId); @@ -211,11 +218,12 @@ public class NoteEditActivity extends Activity implements OnClickListener, 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())) { - // New note + // 创建新笔记或编辑 long folderId = intent.getLongExtra(Notes.INTENT_EXTRA_FOLDER_ID, 0); int widgetId = intent.getIntExtra(Notes.INTENT_EXTRA_WIDGET_ID, AppWidgetManager.INVALID_APPWIDGET_ID); @@ -224,7 +232,7 @@ public class NoteEditActivity extends Activity implements OnClickListener, int bgResId = intent.getIntExtra(Notes.INTENT_EXTRA_BACKGROUND_ID, ResourceParser.getDefaultBgId(this)); - // 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) { @@ -232,6 +240,7 @@ public class NoteEditActivity extends Activity implements OnClickListener, Log.w(TAG, "The call record number is null"); } long noteId = 0; + // 检查是否已存在对应的通话记录笔记 if ((noteId = DataUtils.getNoteIdByPhoneNumberAndCallDate(getContentResolver(), phoneNumber, callDate)) > 0) { mWorkingNote = WorkingNote.load(this, noteId); @@ -241,15 +250,18 @@ public class NoteEditActivity extends Activity implements OnClickListener, return false; } } else { + // 创建新的通话记录笔记 mWorkingNote = WorkingNote.createEmptyNote(this, folderId, widgetId, widgetType, bgResId); mWorkingNote.convertToCallNote(phoneNumber, callDate); } } else { + // 创建普通新笔记 mWorkingNote = WorkingNote.createEmptyNote(this, folderId, widgetId, widgetType, bgResId); } + // 显示软键盘 getWindow().setSoftInputMode( WindowManager.LayoutParams.SOFT_INPUT_ADJUST_RESIZE | WindowManager.LayoutParams.SOFT_INPUT_STATE_VISIBLE); @@ -262,39 +274,55 @@ public class NoteEditActivity extends Activity implements OnClickListener, return true; } + /** + * Activity恢复时刷新界面 + */ @Override protected void onResume() { super.onResume(); initNoteScreen(); } + /** + * 初始化笔记编辑界面 + */ private void initNoteScreen() { + // 设置编辑器字体大小 mNoteEditor.setTextAppearance(this, TextAppearanceResources .getTexAppearanceResource(mFontSizeId)); + + // 根据笔记模式初始化界面 if (mWorkingNote.getCheckListMode() == TextNote.MODE_CHECK_LIST) { + // 清单模式 switchToListMode(mWorkingNote.getContent()); } else { + // 普通文本模式，高亮搜索词 mNoteEditor.setText(getHighlightQueryResult(mWorkingNote.getContent(), mUserQuery)); mNoteEditor.setSelection(mNoteEditor.getText().length()); } + + // 隐藏所有背景颜色选中标记 for (Integer id : sBgSelectorSelectionMap.keySet()) { findViewById(sBgSelectorSelectionMap.get(id)).setVisibility(View.GONE); } + + // 设置背景颜色 mHeadViewPanel.setBackgroundResource(mWorkingNote.getTitleBgResId()); mNoteEditorPanel.setBackgroundResource(mWorkingNote.getBgColorResId()); + // 设置修改时间显示 mNoteHeaderHolder.tvModified.setText(DateUtils.formatDateTime(this, mWorkingNote.getModifiedDate(), DateUtils.FORMAT_SHOW_DATE | DateUtils.FORMAT_NUMERIC_DATE | DateUtils.FORMAT_SHOW_TIME | DateUtils.FORMAT_SHOW_YEAR)); - /** - * TODO: Add the menu for setting alert. Currently disable it because the DateTimePicker - * is not ready - */ + // 显示提醒信息 showAlertHeader(); } + /** + * 显示或隐藏提醒相关的UI组件 + */ private void showAlertHeader() { if (mWorkingNote.hasClockAlert()) { long time = System.currentTimeMillis(); @@ -312,20 +340,22 @@ public class NoteEditActivity extends Activity implements OnClickListener, }; } + /** + * 处理新的Intent（活动被重新启动时） + */ @Override protected void onNewIntent(Intent intent) { super.onNewIntent(intent); initActivityState(intent); } + /** + * 保存活动状态 + */ @Override protected void onSaveInstanceState(Bundle outState) { super.onSaveInstanceState(outState); - /** - * For new note without note id, we should firstly save it to - * generate a id. If the editing note is not worth saving, there - * is no id which is equivalent to create new note - */ + // 保存新笔记的ID if (!mWorkingNote.existInDatabase()) { saveNote(); } @@ -333,6 +363,9 @@ public class NoteEditActivity extends Activity implements OnClickListener, Log.d(TAG, "Save working note id: " + mWorkingNote.getNoteId() + " onSaveInstanceState"); } + /** + * 触摸事件分发，用于点击选择器外部时关闭选择器 + */ @Override public boolean dispatchTouchEvent(MotionEvent ev) { if (mNoteBgColorSelector.getVisibility() == View.VISIBLE @@ -349,6 +382,9 @@ public class NoteEditActivity extends Activity implements OnClickListener, return super.dispatchTouchEvent(ev); } + /** + * 判断触摸点是否在指定视图范围内 + */ private boolean inRangeOfView(View view, MotionEvent ev) { int []location = new int[2]; view.getLocationOnScreen(location); @@ -358,11 +394,14 @@ public class NoteEditActivity extends Activity implements OnClickListener, || ev.getX() > (x + view.getWidth()) || ev.getY() < y || ev.getY() > (y + view.getHeight())) { - return false; - } + return false; + } return true; } + /** + * 初始化视图资源和事件监听 + */ private void initResources() { mHeadViewPanel = findViewById(R.id.note_title); mNoteHeaderHolder = new HeadViewHolder(); @@ -374,40 +413,49 @@ public class NoteEditActivity extends Activity implements OnClickListener, mNoteEditor = (EditText) findViewById(R.id.note_edit_view); mNoteEditorPanel = findViewById(R.id.sv_note_edit); mNoteBgColorSelector = findViewById(R.id.note_bg_color_selector); + + // 设置背景颜色选择按钮的点击监听 for (int id : sBgSelectorBtnsMap.keySet()) { ImageView iv = (ImageView) findViewById(id); iv.setOnClickListener(this); } mFontSizeSelector = findViewById(R.id.font_size_selector); + // 设置字体大小选择项的点击监听 for (int id : sFontSizeBtnsMap.keySet()) { View view = findViewById(id); view.setOnClickListener(this); }; + mSharedPrefs = PreferenceManager.getDefaultSharedPreferences(this); mFontSizeId = mSharedPrefs.getInt(PREFERENCE_FONT_SIZE, ResourceParser.BG_DEFAULT_FONT_SIZE); - /** - * HACKME: Fix bug of store the resource id in shared preference. - * The id may larger than the length of resources, in this case, - * return the {@link ResourceParser#BG_DEFAULT_FONT_SIZE} - */ + + // 修复字体大小ID可能超出范围的问题 if(mFontSizeId >= TextAppearanceResources.getResourcesSize()) { mFontSizeId = ResourceParser.BG_DEFAULT_FONT_SIZE; } mEditTextList = (LinearLayout) findViewById(R.id.note_edit_list); } + /** + * Activity暂停时保存笔记 + */ @Override protected void onPause() { super.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); + // 根据小部件类型设置对应的广播接收器 if (mWorkingNote.getWidgetType() == Notes.TYPE_WIDGET_2X) { intent.setClass(this, NoteWidgetProvider_2x.class); } else if (mWorkingNote.getWidgetType() == Notes.TYPE_WIDGET_4X) { @@ -417,51 +465,77 @@ public class NoteEditActivity extends Activity implements OnClickListener, return; } + // 设置要更新的小部件ID intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_IDS, new int[] { - mWorkingNote.getWidgetId() + mWorkingNote.getWidgetId() }); - sendBroadcast(intent); - setResult(RESULT_OK, intent); + sendBroadcast(intent); // 发送广播通知小部件更新 + setResult(RESULT_OK, intent); // 设置活动结果 } + /** + * 点击事件处理 + */ public void onClick(View v) { int id = v.getId(); if (id == R.id.btn_set_bg_color) { + // 点击背景颜色设置按钮，显示颜色选择器 mNoteBgColorSelector.setVisibility(View.VISIBLE); + // 显示当前选中颜色的标记 findViewById(sBgSelectorSelectionMap.get(mWorkingNote.getBgColorId())).setVisibility( - - View.VISIBLE); + View.VISIBLE); } else if (sBgSelectorBtnsMap.containsKey(id)) { + // 点击了某个背景颜色按钮 + // 隐藏之前选中颜色的标记 findViewById(sBgSelectorSelectionMap.get(mWorkingNote.getBgColorId())).setVisibility( View.GONE); + // 更新笔记的背景颜色ID mWorkingNote.setBgColorId(sBgSelectorBtnsMap.get(id)); - mNoteBgColorSelector.setVisibility(View.GONE); + mNoteBgColorSelector.setVisibility(View.GONE); // 隐藏选择器 } else if (sFontSizeBtnsMap.containsKey(id)) { + // 点击了字体大小选项 + // 隐藏之前选中字体的标记 findViewById(sFontSelectorSelectionMap.get(mFontSizeId)).setVisibility(View.GONE); + // 更新字体大小ID并保存到偏好设置 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()); } else { + // 普通模式：直接设置编辑器的文本外观 mNoteEditor.setTextAppearance(this, TextAppearanceResources.getTexAppearanceResource(mFontSizeId)); } - mFontSizeSelector.setVisibility(View.GONE); + mFontSizeSelector.setVisibility(View.GONE); // 隐藏字体选择器 } } + /** + * 返回键按下事件处理 + */ @Override public void onBackPressed() { + // 如果有设置面板打开，先关闭面板 if(clearSettingState()) { return; } + // 保存笔记后执行默认返回操作 saveNote(); super.onBackPressed(); } + /** + * 清理设置面板状态（关闭打开的面板） + * @return 是否有面板被关闭 + */ private boolean clearSettingState() { if (mNoteBgColorSelector.getVisibility() == View.VISIBLE) { mNoteBgColorSelector.setVisibility(View.GONE); @@ -473,45 +547,66 @@ public class NoteEditActivity extends Activity implements OnClickListener, return false; } + /** + * 背景颜色改变回调（NoteSettingChangedListener接口方法） + */ public void onBackgroundColorChanged() { + // 显示新选中颜色的标记 findViewById(sBgSelectorSelectionMap.get(mWorkingNote.getBgColorId())).setVisibility( View.VISIBLE); + // 更新编辑器面板和头部面板的背景 mNoteEditorPanel.setBackgroundResource(mWorkingNote.getBgColorResId()); mHeadViewPanel.setBackgroundResource(mWorkingNote.getTitleBgResId()); } + /** + * 准备选项菜单 + */ @Override public boolean onPrepareOptionsMenu(Menu menu) { if (isFinishing()) { return true; } - clearSettingState(); - menu.clear(); + clearSettingState(); // 清理设置面板状态 + menu.clear(); // 清空菜单 + + // 根据笔记类型加载不同的菜单 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); } else { menu.findItem(R.id.menu_list_mode).setTitle(R.string.menu_list_mode); } + + // 根据是否有提醒设置菜单项显示 if (mWorkingNote.hasClockAlert()) { menu.findItem(R.id.menu_alert).setVisible(false); + menu.findItem(R.id.menu_delete_remind).setVisible(true); } else { + menu.findItem(R.id.menu_alert).setVisible(true); menu.findItem(R.id.menu_delete_remind).setVisible(false); } return true; } + /** + * 菜单项点击处理 + */ @Override public boolean onOptionsItemSelected(MenuItem item) { switch (item.getItemId()) { case R.id.menu_new_note: + // 创建新笔记 createNewNote(); break; 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); @@ -519,32 +614,38 @@ public class NoteEditActivity extends Activity implements OnClickListener, builder.setPositiveButton(android.R.string.ok, new DialogInterface.OnClickListener() { public void onClick(DialogInterface dialog, int which) { - deleteCurrentNote(); - finish(); + deleteCurrentNote(); // 删除当前笔记 + finish(); // 结束活动 } }); builder.setNegativeButton(android.R.string.cancel, null); builder.show(); break; case R.id.menu_font_size: + // 显示字体大小选择器 mFontSizeSelector.setVisibility(View.VISIBLE); findViewById(sFontSelectorSelectionMap.get(mFontSizeId)).setVisibility(View.VISIBLE); break; case R.id.menu_list_mode: + // 切换清单模式/普通模式 mWorkingNote.setCheckListMode(mWorkingNote.getCheckListMode() == 0 ? TextNote.MODE_CHECK_LIST : 0); break; case R.id.menu_share: + // 分享笔记内容 getWorkingText(); sendTo(this, mWorkingNote.getContent()); break; case R.id.menu_send_to_desktop: + // 发送到桌面快捷方式 sendToDesktop(); break; case R.id.menu_alert: + // 设置提醒 setReminder(); break; case R.id.menu_delete_remind: + // 删除提醒 mWorkingNote.setAlertDate(0, false); break; default: @@ -553,32 +654,39 @@ public class NoteEditActivity extends Activity implements OnClickListener, return true; } + /** + * 设置提醒时间 + */ private void setReminder() { + // 创建日期时间选择对话框 DateTimePickerDialog d = new DateTimePickerDialog(this, System.currentTimeMillis()); d.setOnDateTimeSetListener(new OnDateTimeSetListener() { public void OnDateTimeSet(AlertDialog dialog, long date) { - mWorkingNote.setAlertDate(date , true); + // 设置提醒日期 + mWorkingNote.setAlertDate(date, true); } }); d.show(); } /** - * Share note to apps that support {@link Intent#ACTION_SEND} action - * and {@text/plain} type + * 分享笔记内容到其他应用 */ private void sendTo(Context context, String info) { Intent intent = new Intent(Intent.ACTION_SEND); - intent.putExtra(Intent.EXTRA_TEXT, info); - intent.setType("text/plain"); - context.startActivity(intent); + intent.putExtra(Intent.EXTRA_TEXT, info); // 设置分享文本 + intent.setType("text/plain"); // 设置MIME类型 + context.startActivity(intent); // 启动分享选择器 } + /** + * 创建新笔记 + */ private void createNewNote() { - // Firstly, save current editing notes + // 先保存当前编辑的笔记 saveNote(); - // For safety, start a new NoteEditActivity + // 结束当前活动并启动新的编辑活动 finish(); Intent intent = new Intent(this, NoteEditActivity.class); intent.setAction(Intent.ACTION_INSERT_OR_EDIT); @@ -586,6 +694,9 @@ public class NoteEditActivity extends Activity implements OnClickListener, startActivity(intent); } + /** + * 删除当前笔记 + */ private void deleteCurrentNote() { if (mWorkingNote.existInDatabase()) { HashSet ids = new HashSet(); @@ -595,125 +706,155 @@ public class NoteEditActivity extends Activity implements OnClickListener, } else { Log.d(TAG, "Wrong note id, should not happen"); } + + // 根据同步模式选择删除方式 if (!isSyncMode()) { + // 非同步模式：直接删除 if (!DataUtils.batchDeleteNotes(getContentResolver(), ids)) { Log.e(TAG, "Delete Note error"); } } else { + // 同步模式：移动到垃圾箱 if (!DataUtils.batchMoveToFolder(getContentResolver(), ids, Notes.ID_TRASH_FOLER)) { Log.e(TAG, "Move notes to trash folder error, should not happens"); } } } - mWorkingNote.markDeleted(true); + mWorkingNote.markDeleted(true); // 标记为已删除 } + /** + * 检查是否处于同步模式 + */ private boolean isSyncMode() { return NotesPreferenceActivity.getSyncAccountName(this).trim().length() > 0; } + /** + * 提醒时间改变回调（NoteSettingChangedListener接口方法） + */ 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 - */ + // 对于未保存的笔记，先保存再设置提醒 if (!mWorkingNote.existInDatabase()) { saveNote(); } + if (mWorkingNote.getNoteId() > 0) { + // 创建闹钟意图 Intent intent = new Intent(this, AlarmReceiver.class); intent.setData(ContentUris.withAppendedId(Notes.CONTENT_NOTE_URI, mWorkingNote.getNoteId())); PendingIntent pendingIntent = PendingIntent.getBroadcast(this, 0, intent, 0); AlarmManager alarmManager = ((AlarmManager) getSystemService(ALARM_SERVICE)); - showAlertHeader(); + + showAlertHeader(); // 更新提醒显示 if(!set) { + // 取消提醒 alarmManager.cancel(pendingIntent); } else { + // 设置提醒 alarmManager.set(AlarmManager.RTC_WAKEUP, date, pendingIntent); } } else { - /** - * There is the condition that user has input nothing (the note is - * not worthy saving), we have no note id, remind the user that he - * should input something - */ + // 笔记为空，无法设置提醒 Log.e(TAG, "Clock alert setting error"); showToast(R.string.error_note_empty_for_clock); } } + /** + * 小部件改变回调（NoteSettingChangedListener接口方法） + */ public void onWidgetChanged() { - updateWidget(); + updateWidget(); // 更新关联的小部件 } + /** + * 清单模式下删除编辑项（OnTextViewChangeListener接口方法） + */ public void onEditTextDelete(int index, String text) { int childCount = mEditTextList.getChildCount(); if (childCount == 1) { - return; + return; // 只有一个项时不删除 } + // 更新后面所有项的索引 for (int i = index + 1; i < childCount; i++) { ((NoteEditText) mEditTextList.getChildAt(i).findViewById(R.id.et_edit_text)) .setIndex(i - 1); } + // 移除指定位置的视图 mEditTextList.removeViewAt(index); NoteEditText edit = null; + // 决定焦点给哪个编辑框 if(index == 0) { - edit = (NoteEditText) mEditTextList.getChildAt(0).findViewById( - R.id.et_edit_text); + edit = (NoteEditText) mEditTextList.getChildAt(0).findViewById(R.id.et_edit_text); } else { - edit = (NoteEditText) mEditTextList.getChildAt(index - 1).findViewById( - R.id.et_edit_text); + edit = (NoteEditText) mEditTextList.getChildAt(index - 1).findViewById(R.id.et_edit_text); } + // 将删除的文本追加到获得焦点的编辑框 int length = edit.length(); edit.append(text); edit.requestFocus(); edit.setSelection(length); } + /** + * 清单模式下插入新编辑项（OnTextViewChangeListener接口方法） + */ public void onEditTextEnter(int index, String text) { - /** - * Should not happen, check for debug - */ + // 安全检查 if(index > mEditTextList.getChildCount()) { Log.e(TAG, "Index out of mEditTextList boundrary, should not happen"); } + // 创建新列表项并插入到指定位置 View view = getListItem(text, index); mEditTextList.addView(view, 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++) { ((NoteEditText) mEditTextList.getChildAt(i).findViewById(R.id.et_edit_text)) .setIndex(i); } } + /** + * 切换到清单模式 + */ private void switchToListMode(String text) { - mEditTextList.removeAllViews(); - String[] items = text.split("\n"); + mEditTextList.removeAllViews(); // 清空现有视图 + String[] items = text.split("\n"); // 按换行符分割文本 int index = 0; for (String item : items) { if(!TextUtils.isEmpty(item)) { + // 为每个非空段落创建列表项 mEditTextList.addView(getListItem(item, index)); index++; } } + // 添加一个空的列表项用于输入新内容 mEditTextList.addView(getListItem("", index)); mEditTextList.getChildAt(index).findViewById(R.id.et_edit_text).requestFocus(); + // 切换显示模式 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); int start = 0; + // 为所有匹配的文本设置背景色 while (m.find(start)) { spannable.setSpan( new BackgroundColorSpan(this.getResources().getColor( @@ -725,27 +866,35 @@ public class NoteEditActivity extends Activity implements OnClickListener, return spannable; } + /** + * 创建清单模式下的列表项视图 + */ 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); 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); } else { + // 取消选中时恢复正常样式 edit.setPaintFlags(Paint.ANTI_ALIAS_FLAG | Paint.DEV_KERN_TEXT_FLAG); } } }); + // 解析清单标记符号 if (item.startsWith(TAG_CHECKED)) { - cb.setChecked(true); + cb.setChecked(true); // 已完成的项 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); + cb.setChecked(false); // 未完成的项 edit.setPaintFlags(Paint.ANTI_ALIAS_FLAG | Paint.DEV_KERN_TEXT_FLAG); item = item.substring(TAG_UNCHECKED.length(), item.length()).trim(); } @@ -756,11 +905,15 @@ public class NoteEditActivity extends Activity implements OnClickListener, return view; } + /** + * 文本变化回调（OnTextViewChangeListener接口方法） + */ public void onTextChange(int index, boolean hasText) { if (index >= mEditTextList.getChildCount()) { Log.e(TAG, "Wrong index, should not happen"); return; } + // 根据是否有文本显示或隐藏复选框 if(hasText) { mEditTextList.getChildAt(index).findViewById(R.id.cb_edit_item).setVisibility(View.VISIBLE); } else { @@ -768,11 +921,17 @@ public class NoteEditActivity extends Activity implements OnClickListener, } } + /** + * 清单模式改变回调（NoteSettingChangedListener接口方法） + */ 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 + " ", "")); } @@ -782,87 +941,98 @@ public class NoteEditActivity extends Activity implements OnClickListener, } } + /** + * 从UI获取当前编辑的文本内容 + * @return 是否存在已完成的项 + */ private boolean getWorkingText() { boolean hasChecked = false; if (mWorkingNote.getCheckListMode() == TextNote.MODE_CHECK_LIST) { + // 清单模式：构建格式化的文本 StringBuilder sb = new StringBuilder(); 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"); hasChecked = true; } else { + // 未完成的项 sb.append(TAG_UNCHECKED).append(" ").append(edit.getText()).append("\n"); } } } mWorkingNote.setWorkingText(sb.toString()); } else { + // 普通模式：直接获取编辑器文本 mWorkingNote.setWorkingText(mNoteEditor.getText().toString()); } return hasChecked; } + /** + * 保存笔记到数据库 + * @return 保存是否成功 + */ private boolean saveNote() { - getWorkingText(); - boolean saved = mWorkingNote.saveNote(); + getWorkingText(); // 从UI获取最新文本 + boolean saved = mWorkingNote.saveNote(); // 保存到数据库 if (saved) { - /** - * There are two modes from List view to edit view, open one note, - * create/edit a node. Opening node requires to the original - * position in the list when back from edit view, while creating a - * new node requires to the top of the list. This code - * {@link #RESULT_OK} is used to identify the create/edit state - */ - setResult(RESULT_OK); + setResult(RESULT_OK); // 设置活动结果 } return saved; } + /** + * 发送笔记到桌面快捷方式 + */ 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()) { saveNote(); } if (mWorkingNote.getNoteId() > 0) { Intent sender = new Intent(); + // 创建快捷方式意图 Intent shortcutIntent = new Intent(this, NoteEditActivity.class); shortcutIntent.setAction(Intent.ACTION_VIEW); shortcutIntent.putExtra(Intent.EXTRA_UID, mWorkingNote.getNoteId()); + sender.putExtra(Intent.EXTRA_SHORTCUT_INTENT, shortcutIntent); sender.putExtra(Intent.EXTRA_SHORTCUT_NAME, makeShortcutIconTitle(mWorkingNote.getContent())); sender.putExtra(Intent.EXTRA_SHORTCUT_ICON_RESOURCE, Intent.ShortcutIconResource.fromContext(this, R.drawable.icon_app)); - sender.putExtra("duplicate", true); + sender.putExtra("duplicate", true); // 允许重复创建 sender.setAction("com.android.launcher.action.INSTALL_SHORTCUT"); + showToast(R.string.info_note_enter_desktop); sendBroadcast(sender); } else { - /** - * There is the condition that user has input nothing (the note is - * not worthy saving), we have no note id, remind the user that he - * should input something - */ + // 笔记为空，无法创建快捷方式 Log.e(TAG, "Send to desktop error"); showToast(R.string.error_note_empty_for_send_to_desktop); } } + /** + * 生成桌面快捷方式的标题 + */ 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; } + /** + * 显示Toast提示 + */ private void showToast(int resId) { showToast(resId, Toast.LENGTH_SHORT); } @@ -870,4 +1040,4 @@ public class NoteEditActivity extends Activity implements OnClickListener, private void showToast(int resId, int duration) { Toast.makeText(this, resId, duration).show(); } -} +} \ No newline at end of file diff --git a/src/notes/ui/NoteEditText.java b/src/notes/ui/NoteEditText.java index 2afe2a8..8122993 100644 --- a/src/notes/ui/NoteEditText.java +++ b/src/notes/ui/NoteEditText.java @@ -37,115 +37,167 @@ import net.micode.notes.R; import java.util.HashMap; import java.util.Map; +/** + * 自定义编辑文本框，用于笔记应用的清单模式 + * 支持特殊的删除和回车逻辑，以及链接处理功能 + */ public class NoteEditText extends EditText { private static final String TAG = "NoteEditText"; - private int mIndex; - private int mSelectionStartBeforeDelete; + 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:" ; // 网页协议 + 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 新编辑框的索引（当前索引+1） + * @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; + /** + * 构造函数1：仅通过Context创建 + */ public NoteEditText(Context context) { super(context, null); - mIndex = 0; + mIndex = 0; // 初始化索引为0 } + /** + * 设置当前编辑框在列表中的索引 + * @param index 索引位置 + */ public void setIndex(int index) { mIndex = index; } + /** + * 设置文本变化监听器 + * @param listener 监听器实例 + */ public void setOnTextViewChangeListener(OnTextViewChangeListener listener) { mOnTextViewChangeListener = listener; } + /** + * 构造函数2：通过Context和AttributeSet创建（XML布局使用） + */ public NoteEditText(Context context, AttributeSet attrs) { super(context, attrs, android.R.attr.editTextStyle); } + /** + * 构造函数3：通过Context、AttributeSet和样式定义创建 + */ public NoteEditText(Context context, AttributeSet attrs, int defStyle) { super(context, attrs, defStyle); // TODO Auto-generated constructor stub } + /** + * 触摸事件处理 - 用于精确的链接点击定位 + * 当手指按下时，计算点击位置对应的字符偏移量，并设置光标到那里 + */ @Override public boolean onTouchEvent(MotionEvent event) { switch (event.getAction()) { - case MotionEvent.ACTION_DOWN: - + case MotionEvent.ACTION_DOWN: // 手指按下动作 + // 计算点击处在文本内容中的准确坐标 int x = (int) event.getX(); int y = (int) event.getY(); + // 减去内边距，得到文本区域内的坐标 x -= getTotalPaddingLeft(); y -= getTotalPaddingTop(); + // 加上滚动偏移量，得到文本内容中的绝对坐标 x += getScrollX(); y += getScrollY(); + // 获取文本布局对象 Layout layout = getLayout(); + // 根据y坐标找到对应的行号 int line = layout.getLineForVertical(y); + // 根据x坐标在该行找到对应的字符偏移量 int off = layout.getOffsetForHorizontal(line, x); + // 将光标设置到计算出的偏移量位置 Selection.setSelection(getText(), off); break; } + // 调用父类方法处理其他触摸逻辑（如长按弹出菜单） return super.onTouchEvent(event); } + /** + * 按键按下事件处理 + * 主要记录删除键按下时光标的位置 + */ @Override public boolean onKeyDown(int keyCode, KeyEvent event) { switch (keyCode) { - case KeyEvent.KEYCODE_ENTER: + case KeyEvent.KEYCODE_ENTER: // 回车键 if (mOnTextViewChangeListener != null) { + // 如果监听器存在，返回false让onKeyUp处理 return false; } break; - case KeyEvent.KEYCODE_DEL: + case KeyEvent.KEYCODE_DEL: // 删除键（退格键） + // 记录删除前光标的起始位置，用于在onKeyUp中判断是否在行首 mSelectionStartBeforeDelete = getSelectionStart(); break; default: break; } + // 其他按键交给父类处理 return super.onKeyDown(keyCode, event); } + /** + * 按键抬起事件处理 - 核心逻辑实现 + * 处理删除键和回车键的特殊行为 + */ @Override public boolean onKeyUp(int keyCode, KeyEvent event) { switch(keyCode) { case KeyEvent.KEYCODE_DEL: if (mOnTextViewChangeListener != null) { + // 判断条件：光标在行首（位置0）且不是第一个编辑框（索引不为0） if (0 == mSelectionStartBeforeDelete && mIndex != 0) { + // 触发删除监听，通知Activity删除当前编辑框 mOnTextViewChangeListener.onEditTextDelete(mIndex, getText().toString()); - return true; + return true; // 消费此事件，阻止父类处理 } } else { Log.d(TAG, "OnTextViewChangeListener was not seted"); @@ -153,9 +205,13 @@ 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,51 +223,72 @@ public class NoteEditText extends EditText { return super.onKeyUp(keyCode, event); } + /** + * 焦点变化事件处理 + * 当编辑框获得或失去焦点时，根据文本内容通知监听器 + */ @Override protected void onFocusChanged(boolean focused, int direction, Rect previouslyFocusedRect) { if (mOnTextViewChangeListener != null) { + // 如果失去焦点且文本为空，通知无文本状态 if (!focused && TextUtils.isEmpty(getText())) { mOnTextViewChangeListener.onTextChange(mIndex, false); } else { + // 其他情况（获得焦点，或失去焦点但文本不为空），通知有文本状态 mOnTextViewChangeListener.onTextChange(mIndex, true); } } super.onFocusChanged(focused, direction, previouslyFocusedRect); } + /** + * 创建上下文菜单（长按编辑框时弹出的菜单） + * 特别处理文本中的链接，为链接添加对应的操作菜单项 + */ @Override protected void onCreateContextMenu(ContextMenu menu) { + // 检查当前文本是否包含样式（如链接） if (getText() instanceof Spanned) { + // 获取选区的开始和结束位置 int selStart = getSelectionStart(); int selEnd = getSelectionEnd(); + // 计算选区的最小和最大位置（考虑用户可能从右向左选择） int min = Math.min(selStart, selEnd); int max = Math.max(selStart, selEnd); + // 从文本中获取选区范围内的所有链接 final URLSpan[] urls = ((Spanned) getText()).getSpans(min, max, URLSpan.class); + // 如果选区内有且仅有一个链接 if (urls.length == 1) { - int defaultResId = 0; + int defaultResId = 0; // 菜单项文本的资源ID + + // 遍历协议映射，检查链接的URL包含哪种协议 for(String schema: sSchemaActionResMap.keySet()) { if(urls[0].getURL().indexOf(schema) >= 0) { + // 找到匹配的协议，获取对应的字符串资源ID defaultResId = sSchemaActionResMap.get(schema); break; } } + // 如果没有匹配到预定义的协议，使用"其他"选项 if (defaultResId == 0) { 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; + return true; // 消费此事件 } }); } } + // 调用父类方法添加系统默认的菜单项（复制、粘贴等） super.onCreateContextMenu(menu); } -} +} \ No newline at end of file diff --git a/src/notes/ui/NoteItemData.java b/src/notes/ui/NoteItemData.java index 0f5a878..c1601e9 100644 --- a/src/notes/ui/NoteItemData.java +++ b/src/notes/ui/NoteItemData.java @@ -25,200 +25,343 @@ import net.micode.notes.data.Notes; import net.micode.notes.data.Notes.NoteColumns; import net.micode.notes.tool.DataUtils; - +/** + * 笔记列表项的数据封装类。 + * 这个类的主要作用是将数据库查询结果（Cursor对象）中的原始数据 + * 封装成一个易于使用的Java对象（POJO），并添加一些业务逻辑判断。 + * 它代表了笔记列表中的一个条目，这个条目可能是一条笔记、一个文件夹或系统文件夹。 + */ public class NoteItemData { + /** + * 数据库查询的列投影（Projection），定义了要从数据库中查询哪些列。 + * 这个数组中的列名顺序很重要，后面的列索引常量要与之对应。 + */ 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; - + /** + * 列索引常量，对应上面PROJECTION数组中各列的位置。 + * 使用常量而不是直接写数字（如0,1,2）可以提高代码可读性和可维护性。 + */ + 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; // 笔记/文件夹的唯一标识ID + private long mAlertDate; // 提醒时间戳（毫秒） + private int mBgColorId; // 背景颜色资源ID + private long mCreatedDate; // 创建时间戳（毫秒） + private boolean mHasAttachment; // 是否有附件（true/false） + 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 context 上下文，用于获取内容解析器等系统服务 + * @param 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); mCreatedDate = cursor.getLong(CREATED_DATE_COLUMN); + // 将整数值转换为布尔值：大于0表示有附件（true），否则为false mHasAttachment = (cursor.getInt(HAS_ATTACHMENT_COLUMN) > 0) ? true : false; mModifiedDate = cursor.getLong(MODIFIED_DATE_COLUMN); mNotesCount = cursor.getInt(NOTES_COUNT_COLUMN); mParentId = cursor.getLong(PARENT_ID_COLUMN); mSnippet = cursor.getString(SNIPPET_COLUMN); + // 清理摘要文本中的清单标记符号（对勾和方框），让显示更干净 mSnippet = mSnippet.replace(NoteEditActivity.TAG_CHECKED, "").replace( 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) { + // 根据笔记ID查询对应的电话号码 mPhoneNumber = DataUtils.getCallNumberByNoteId(context.getContentResolver(), mId); if (!TextUtils.isEmpty(mPhoneNumber)) { + // 如果电话号码不为空，通过联系人提供者查询对应的联系人姓名 mName = Contact.getContact(context, mPhoneNumber); if (mName == null) { + // 如果查询不到联系人，则用电话号码本身作为显示名称 mName = mPhoneNumber; } } } + // 确保姓名不为null，避免后续使用时报错 if (mName == null) { mName = ""; } + + // 检查当前项在列表中的位置状态（如是否是第一项、最后一项等） checkPostion(cursor); } + /** + * 检查当前数据项在游标（列表）中的位置状态 + * 这些状态信息可能用于控制列表项的UI显示（如分割线、边距等） + * @param cursor 数据库游标 + */ private void checkPostion(Cursor cursor) { - mIsLastItem = cursor.isLast() ? true : false; - mIsFirstItem = cursor.isFirst() ? true : false; - mIsOnlyOneItem = (cursor.getCount() == 1); + // 使用游标的方法判断位置 + mIsLastItem = cursor.isLast() ? true : false; // 是否是最后一项 + mIsFirstItem = cursor.isFirst() ? true : false; // 是否是第一项 + mIsOnlyOneItem = (cursor.getCount() == 1); // 是否只有一项 + + // 初始化位置关系标志为false 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; } else { + // 如果后面没有项了，说明只有一个笔记跟在文件夹后面 mIsOneNoteFollowingFolder = true; } } + // 将游标移回原来的位置 if (!cursor.moveToNext()) { + // 理论上不应该发生，如果发生了说明游标状态有问题 throw new IllegalStateException("cursor move to previous but can't move back"); } } } } + // ========== 以下是一系列的getter方法，用于外部获取对象的属性值 ========== + + /** + * 判断当前笔记是否是唯一一个紧跟在文件夹后面的笔记 + * @return 如果是，返回true + */ public boolean isOneFollowingFolder() { return mIsOneNoteFollowingFolder; } + /** + * 判断当前笔记是否是多个紧跟在文件夹后面的笔记之一 + * @return 如果是，返回true + */ public boolean isMultiFollowingFolder() { return mIsMultiNotesFollowingFolder; } + /** + * 判断当前项是否是列表中的最后一项 + * @return 如果是最后一项，返回true + */ public boolean isLast() { return mIsLastItem; } + /** + * 获取通话记录对应的联系人姓名（如果不是通话记录，返回空字符串） + * @return 联系人姓名 + */ public String getCallName() { return mName; } + /** + * 判断当前项是否是列表中的第一项 + * @return 如果是第一项，返回true + */ public boolean isFirst() { return mIsFirstItem; } + /** + * 判断当前项是否是列表中唯一的一项 + * @return 如果是唯一项，返回true + */ public boolean isSingle() { return mIsOnlyOneItem; } + /** + * 获取笔记/文件夹的ID + * @return 唯一标识ID + */ 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（mAlertDate > 0） + */ public boolean hasAlert() { return (mAlertDate > 0); } + /** + * 判断是否是通话记录笔记 + * 条件：属于通话记录文件夹 且 有有效的电话号码 + * @return 是通话记录笔记返回true + */ public boolean isCallRecord() { return (mParentId == Notes.ID_CALL_RECORD_FOLDER && !TextUtils.isEmpty(mPhoneNumber)); } + /** + * 静态方法：直接从游标中获取笔记类型 + * 这个方法不需要创建NoteItemData对象，效率更高 + * @param cursor 数据库游标 + * @return 笔记类型 + */ public static int getNoteType(Cursor cursor) { return cursor.getInt(TYPE_COLUMN); } -} +} \ No newline at end of file diff --git a/src/notes/ui/NotesListActivity.java b/src/notes/ui/NotesListActivity.java index e843aec..56ecd10 100644 --- a/src/notes/ui/NotesListActivity.java +++ b/src/notes/ui/NotesListActivity.java @@ -78,99 +78,119 @@ 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 FOLDER_NOTE_LIST_QUERY_TOKEN = 0; // 查询文件夹下的笔记列表 + private static final int FOLDER_LIST_QUERY_TOKEN = 1; // 查询可用的文件夹列表（用于移动操作） - private static final int MENU_FOLDER_VIEW = 1; - - private static final int MENU_FOLDER_CHANGE_NAME = 2; + // 文件夹上下文菜单的菜单项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; // 修改文件夹名称 + // 偏好设置的键名，用于标记是否已经添加过应用介绍笔记 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"; - + // 成员变量声明 + private ListEditState mState; // 当前列表状态 + private BackgroundQueryHandler mBackgroundQueryHandler; // 后台查询处理器 + private NotesListAdapter mNotesListAdapter; // 列表适配器，负责数据与列表项的绑定 + private ListView mNotesListView; // 列表视图 + 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; - private NoteItemData mFocusNoteDataItem; - - private static final String NORMAL_SELECTION = NoteColumns.PARENT_ID + "=?"; + private NoteItemData mFocusNoteDataItem; // 当前获得焦点的数据项（长按时记录） + // 数据库查询条件（Selection） + private static final String NORMAL_SELECTION = NoteColumns.PARENT_ID + "=?"; // 普通查询：父文件夹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)"; + // 根目录查询条件：包含普通文件夹/笔记 或者 有内容的通话记录文件夹 - 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; // 创建新笔记 + /** + * Activity生命周期方法：创建时调用 + */ @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); + // 设置活动布局 setContentView(R.layout.note_list); + // 初始化视图、变量等资源 initResources(); /** - * Insert an introduction when user firstly use this application + * 当用户第一次使用此应用时，插入一个介绍性的笔记 */ setAppInfoFromRawRes(); } + /** + * 处理从其他活动返回的结果 + */ @Override protected void onActivityResult(int requestCode, int resultCode, Intent data) { + // 如果是从笔记编辑活动返回并且操作成功，刷新列表 if (resultCode == RESULT_OK && (requestCode == REQUEST_CODE_OPEN_NODE || requestCode == REQUEST_CODE_NEW_NODE)) { + // 将适配器的游标设为null，触发重新查询 mNotesListAdapter.changeCursor(null); } else { super.onActivityResult(requestCode, resultCode, data); } } + /** + * 从raw资源文件夹读取介绍文本，并创建为笔记（仅第一次使用时执行） + */ private void setAppInfoFromRawRes() { + // 获取偏好设置 SharedPreferences sp = PreferenceManager.getDefaultSharedPreferences(this); + // 检查是否已经添加过介绍笔记 if (!sp.getBoolean(PREFERENCE_ADD_INTRODUCTION, false)) { - StringBuilder sb = new StringBuilder(); + StringBuilder sb = new StringBuilder(); // 用于拼接读取的文本 InputStream in = null; try { - in = getResources().openRawResource(R.raw.introduction); + // 从raw资源文件夹打开介绍文件 + in = getResources().openRawResource(R.raw.introduction); if (in != null) { + // 使用缓冲读取器逐行读取文件内容 InputStreamReader isr = new InputStreamReader(in); BufferedReader br = new BufferedReader(isr); - char [] buf = new char[1024]; + char [] buf = new char[1024]; // 缓冲区 int len = 0; while ((len = br.read(buf)) > 0) { - sb.append(buf, 0, len); + sb.append(buf, 0, len); // 将读取的内容追加到StringBuilder } } else { Log.e(TAG, "Read introduction file error"); @@ -180,21 +200,25 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt e.printStackTrace(); return; } finally { + // 确保输入流被关闭 if(in != null) { try { in.close(); } catch (IOException e) { - // TODO Auto-generated catch block e.printStackTrace(); } } } + // 创建一个新的空笔记（在根目录下） WorkingNote note = WorkingNote.createEmptyNote(this, Notes.ID_ROOT_FOLDER, AppWidgetManager.INVALID_APPWIDGET_ID, Notes.TYPE_WIDGET_INVALIDE, ResourceParser.RED); + // 设置笔记内容为读取的介绍文本 note.setWorkingText(sb.toString()); + // 保存笔记 if (note.saveNote()) { + // 保存成功，在偏好设置中标记已添加介绍 sp.edit().putBoolean(PREFERENCE_ADD_INTRODUCTION, true).commit(); } else { Log.e(TAG, "Save introduction note error"); @@ -203,116 +227,168 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt } } + /** + * Activity生命周期方法：开始时调用 + */ @Override protected void onStart() { super.onStart(); + // 开始异步查询笔记列表 startAsyncNotesListQuery(); } + /** + * 初始化所有视图资源和变量 + */ private void initResources() { - mContentResolver = this.getContentResolver(); - mBackgroundQueryHandler = new BackgroundQueryHandler(this.getContentResolver()); - mCurrentFolderId = Notes.ID_ROOT_FOLDER; - mNotesListView = (ListView) findViewById(R.id.notes_list); + mContentResolver = this.getContentResolver(); // 获取内容解析器实例 + mBackgroundQueryHandler = new BackgroundQueryHandler(this.getContentResolver()); // 创建后台查询处理器 + mCurrentFolderId = Notes.ID_ROOT_FOLDER; // 初始当前文件夹为根目录 + mNotesListView = (ListView) findViewById(R.id.notes_list); // 查找列表视图 + // 为列表添加脚部视图（可能用于显示空白区域或加载更多） mNotesListView.addFooterView(LayoutInflater.from(this).inflate(R.layout.note_list_footer, null), null, false); + // 设置列表项点击监听器 mNotesListView.setOnItemClickListener(new OnListItemClickListener()); + // 设置列表项长按监听器（本活动实现了该接口） mNotesListView.setOnItemLongClickListener(this); + // 创建列表适配器 mNotesListAdapter = new NotesListAdapter(this); - mNotesListView.setAdapter(mNotesListAdapter); - mAddNewNote = (Button) findViewById(R.id.btn_new_note); - mAddNewNote.setOnClickListener(this); + mNotesListView.setAdapter(mNotesListAdapter); // 为列表设置适配器 + mAddNewNote = (Button) findViewById(R.id.btn_new_note); // "新建笔记"按钮 + mAddNewNote.setOnClickListener(this); // 设置按钮点击监听器 + // 设置按钮触摸监听器，用于处理特殊触摸区域的事件分发 mAddNewNote.setOnTouchListener(new NewNoteOnTouchListener()); - mDispatch = false; + mDispatch = false; // 初始化事件分发标志 mDispatchY = 0; mOriginY = 0; - mTitleBar = (TextView) findViewById(R.id.tv_title_bar); - mState = ListEditState.NOTE_LIST; - mModeCallBack = new ModeCallback(); + mTitleBar = (TextView) findViewById(R.id.tv_title_bar); // 标题栏 + mState = ListEditState.NOTE_LIST; // 初始状态为根目录笔记列表 + mModeCallBack = new ModeCallback(); // 创建多选模式回调实例 } + /** + * 多选模式回调类，实现了MultiChoiceModeListener接口 + * 当用户长按笔记进入多选模式时，顶部会出现一个上下文操作栏（ActionMode） + */ private class ModeCallback implements ListView.MultiChoiceModeListener, OnMenuItemClickListener { - private DropdownMenu mDropDownMenu; - private ActionMode mActionMode; - private MenuItem mMoveMenu; + private DropdownMenu mDropDownMenu; // 下拉菜单（用于全选/取消全选） + private ActionMode mActionMode; // 动作模式实例 + private MenuItem mMoveMenu; // "移动"菜单项 + /** + * 创建动作模式时调用（进入多选模式时） + */ public boolean onCreateActionMode(ActionMode mode, Menu menu) { + // 从菜单资源文件加载多选模式下的菜单项 getMenuInflater().inflate(R.menu.note_list_options, menu); + // 为"删除"菜单项设置点击监听器 menu.findItem(R.id.delete).setOnMenuItemClickListener(this); + // 获取"移动"菜单项 mMoveMenu = menu.findItem(R.id.move); + // 判断是否显示"移动"菜单项：通话记录笔记或没有用户文件夹时隐藏 if (mFocusNoteDataItem.getParentId() == Notes.ID_CALL_RECORD_FOLDER || DataUtils.getUserFolderCount(mContentResolver) == 0) { mMoveMenu.setVisible(false); } else { mMoveMenu.setVisible(true); - mMoveMenu.setOnMenuItemClickListener(this); + mMoveMenu.setOnMenuItemClickListener(this); // 设置点击监听器 } - mActionMode = mode; - mNotesListAdapter.setChoiceMode(true); - mNotesListView.setLongClickable(false); - mAddNewNote.setVisibility(View.GONE); + mActionMode = mode; // 保存动作模式实例 + mNotesListAdapter.setChoiceMode(true); // 通知适配器进入多选模式 + mNotesListView.setLongClickable(false); // 禁用长按（避免冲突） + mAddNewNote.setVisibility(View.GONE); // 隐藏"新建笔记"按钮 + // 设置自定义视图（包含下拉菜单） View customView = LayoutInflater.from(NotesListActivity.this).inflate( R.layout.note_list_dropdown_menu, null); mode.setCustomView(customView); + // 初始化下拉菜单 mDropDownMenu = new DropdownMenu(NotesListActivity.this, (Button) customView.findViewById(R.id.selection_menu), R.menu.note_list_dropdown); + // 设置下拉菜单项点击监听器 mDropDownMenu.setOnDropdownMenuItemClickListener(new PopupMenu.OnMenuItemClickListener(){ public boolean onMenuItemClick(MenuItem item) { + // 切换全选/取消全选状态 mNotesListAdapter.selectAll(!mNotesListAdapter.isAllSelected()); - updateMenu(); + updateMenu(); // 更新菜单显示 return true; } - }); return true; } + /** + * 更新菜单显示（主要是更新选中数量和全选状态） + */ private void updateMenu() { - int selectedCount = mNotesListAdapter.getSelectedCount(); - // Update dropdown menu + int selectedCount = mNotesListAdapter.getSelectedCount(); // 获取选中数量 + // 更新下拉菜单标题（显示选中数量） String format = getResources().getString(R.string.menu_select_title, selectedCount); mDropDownMenu.setTitle(format); + // 获取全选菜单项 MenuItem item = mDropDownMenu.findItem(R.id.action_select_all); if (item != null) { if (mNotesListAdapter.isAllSelected()) { + // 如果已全选，显示"取消全选" item.setChecked(true); item.setTitle(R.string.menu_deselect_all); } else { + // 如果未全选，显示"全选" item.setChecked(false); item.setTitle(R.string.menu_select_all); } } } + /** + * 准备动作模式时调用（每次显示菜单前） + */ public boolean onPrepareActionMode(ActionMode mode, Menu menu) { // TODO Auto-generated method stub return false; } + /** + * 动作模式菜单项点击处理（由于我们为每个菜单项单独设置了监听器，这里可能不需要处理） + */ public boolean onActionItemClicked(ActionMode mode, MenuItem item) { // TODO Auto-generated method stub return false; } + /** + * 销毁动作模式时调用（退出多选模式时） + */ public void onDestroyActionMode(ActionMode mode) { - mNotesListAdapter.setChoiceMode(false); - mNotesListView.setLongClickable(true); - mAddNewNote.setVisibility(View.VISIBLE); + mNotesListAdapter.setChoiceMode(false); // 通知适配器退出多选模式 + mNotesListView.setLongClickable(true); // 恢复长按功能 + mAddNewNote.setVisibility(View.VISIBLE); // 显示"新建笔记"按钮 } + /** + * 手动结束动作模式（用于操作完成后退出多选模式） + */ public void finishActionMode() { mActionMode.finish(); } + /** + * 当列表项选中状态改变时调用 + */ public void onItemCheckedStateChanged(ActionMode mode, int position, long id, - boolean checked) { + boolean checked) { + // 通知适配器更新指定位置的选中状态 mNotesListAdapter.setCheckedItem(position, checked); - updateMenu(); + updateMenu(); // 更新菜单显示 } + /** + * 处理菜单项点击事件（OnMenuItemClickListener接口方法） + */ public boolean onMenuItemClick(MenuItem item) { + // 检查是否有选中的项 if (mNotesListAdapter.getSelectedCount() == 0) { Toast.makeText(NotesListActivity.this, getString(R.string.menu_select_none), Toast.LENGTH_SHORT).show(); @@ -321,22 +397,24 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt switch (item.getItemId()) { case R.id.delete: + // 批量删除：弹出确认对话框 AlertDialog.Builder builder = new AlertDialog.Builder(NotesListActivity.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_notes, - mNotesListAdapter.getSelectedCount())); + mNotesListAdapter.getSelectedCount())); builder.setPositiveButton(android.R.string.ok, - new DialogInterface.OnClickListener() { - public void onClick(DialogInterface dialog, - int which) { - batchDelete(); - } - }); + new DialogInterface.OnClickListener() { + public void onClick(DialogInterface dialog, + int which) { + batchDelete(); // 执行批量删除 + } + }); builder.setNegativeButton(android.R.string.cancel, null); builder.show(); break; case R.id.move: + // 批量移动：查询可用的目标文件夹 startQueryDestinationFolders(); break; default: @@ -346,48 +424,55 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt } } + /** + * "新建笔记"按钮的触摸监听器，用于处理按钮透明区域的特殊触摸事件分发 + * HACKME: 这是一个针对特定UI设计的 hack + */ private class NewNoteOnTouchListener implements OnTouchListener { public boolean onTouch(View v, MotionEvent event) { switch (event.getAction()) { case MotionEvent.ACTION_DOWN: { + // 获取屏幕高度和按钮高度 Display display = getWindowManager().getDefaultDisplay(); int screenHeight = display.getHeight(); int newNoteViewHeight = mAddNewNote.getHeight(); - int start = screenHeight - newNoteViewHeight; - int eventY = start + (int) event.getY(); + int start = screenHeight - newNoteViewHeight; // 按钮顶部Y坐标 + int eventY = start + (int) event.getY(); // 触摸点在屏幕中的Y坐标 + /** - * Minus TitleBar's height + * 减去标题栏的高度（如果在子文件夹状态下） */ if (mState == ListEditState.SUB_FOLDER) { eventY -= mTitleBar.getHeight(); start -= mTitleBar.getHeight(); } + /** - * HACKME:When click the transparent part of "New Note" button, dispatch - * the event to the list view behind this button. The transparent part of - * "New Note" button could be expressed by formula y=-0.12x+94（Unit:pixel） - * and the line top of the button. The coordinate based on left of the "New - * Note" button. The 94 represents maximum height of the transparent part. - * 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. + * HACKME: 当点击"新建笔记"按钮的透明部分时，将触摸事件分发给后面的列表视图。 + * 按钮的透明部分可以用公式 y=-0.12x+94（单位：像素）和按钮顶部线表示。 + * 坐标基于按钮左侧。94代表透明部分的最大高度。 + * 注意：如果按钮背景改变，公式也应该改变。这很糟糕，只是为了满足UI设计师的强烈要求。 */ if (event.getY() < (event.getX() * (-0.12) + 94)) { + // 获取列表的最后一个子视图（最底部的项） View view = mNotesListView.getChildAt(mNotesListView.getChildCount() - 1 - mNotesListView.getFooterViewsCount()); if (view != null && view.getBottom() > start && (view.getTop() < (start + 94))) { + // 记录原始坐标，计算分发后的坐标 mOriginY = (int) event.getY(); mDispatchY = eventY; - event.setLocation(event.getX(), mDispatchY); - mDispatch = true; - return mNotesListView.dispatchTouchEvent(event); + event.setLocation(event.getX(), mDispatchY); // 修改事件坐标 + mDispatch = true; // 标记开始分发 + return mNotesListView.dispatchTouchEvent(event); // 分发给列表视图 } } break; } case MotionEvent.ACTION_MOVE: { if (mDispatch) { + // 继续分发移动事件，更新坐标 mDispatchY += (int) event.getY() - mOriginY; event.setLocation(event.getX(), mDispatchY); return mNotesListView.dispatchTouchEvent(event); @@ -396,6 +481,7 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt } default: { if (mDispatch) { + // 分发结束事件，并重置标志 event.setLocation(event.getX(), mDispatchY); mDispatch = false; return mNotesListView.dispatchTouchEvent(event); @@ -403,32 +489,45 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt break; } } - return false; + return false; // 不消费事件，让按钮的onClick正常处理 } - }; + /** + * 开始异步查询当前文件夹下的笔记列表 + */ private void startAsyncNotesListQuery() { + // 根据当前文件夹ID选择查询条件 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"); + String.valueOf(mCurrentFolderId) // 参数：当前文件夹ID + }, NoteColumns.TYPE + " DESC," + NoteColumns.MODIFIED_DATE + " DESC"); // 排序：类型降序，修改日期降序 } + /** + * 后台异步查询处理器，继承自AsyncQueryHandler + * 用于在后台线程执行数据库查询，避免阻塞UI线程 + */ private final class BackgroundQueryHandler extends AsyncQueryHandler { public BackgroundQueryHandler(ContentResolver contentResolver) { super(contentResolver); } + /** + * 查询完成时的回调方法（在UI线程执行） + */ @Override protected void onQueryComplete(int token, Object cookie, Cursor cursor) { switch (token) { case FOLDER_NOTE_LIST_QUERY_TOKEN: + // 笔记列表查询完成：更新适配器的游标（会自动刷新列表） mNotesListAdapter.changeCursor(cursor); break; case FOLDER_LIST_QUERY_TOKEN: + // 文件夹列表查询完成（用于移动操作）：显示文件夹选择对话框 if (cursor != null && cursor.getCount() > 0) { showFolderListMenu(cursor); } else { @@ -441,71 +540,93 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt } } + /** + * 显示文件夹列表选择对话框（用于移动笔记到其他文件夹） + * @param cursor 包含可用文件夹的游标 + */ private void showFolderListMenu(Cursor cursor) { AlertDialog.Builder builder = new AlertDialog.Builder(NotesListActivity.this); - builder.setTitle(R.string.menu_title_select_folder); + builder.setTitle(R.string.menu_title_select_folder); // 设置对话框标题 + // 创建文件夹列表适配器 final FoldersListAdapter adapter = new FoldersListAdapter(this, cursor); + // 设置对话框的列表适配器和项点击监听器 builder.setAdapter(adapter, new DialogInterface.OnClickListener() { - public void onClick(DialogInterface dialog, int which) { + // 执行批量移动到选中的文件夹 DataUtils.batchMoveToFolder(mContentResolver, mNotesListAdapter.getSelectedItemIds(), adapter.getItemId(which)); + // 显示移动成功的提示 Toast.makeText( NotesListActivity.this, getString(R.string.format_move_notes_to_folder, mNotesListAdapter.getSelectedCount(), adapter.getFolderName(NotesListActivity.this, which)), Toast.LENGTH_SHORT).show(); + // 退出多选模式 mModeCallBack.finishActionMode(); } }); - builder.show(); + builder.show(); // 显示对话框 } + /** + * 创建新笔记 + */ 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); + intent.setAction(Intent.ACTION_INSERT_OR_EDIT); // 设置动作为插入或编辑 + intent.putExtra(Notes.INTENT_EXTRA_FOLDER_ID, mCurrentFolderId); // 传递当前文件夹ID + this.startActivityForResult(intent, REQUEST_CODE_NEW_NODE); // 启动笔记编辑活动 } + /** + * 批量删除选中的笔记 + */ private void batchDelete() { + // 使用AsyncTask在后台执行删除操作 new AsyncTask>() { protected HashSet doInBackground(Void... unused) { + // 获取选中的笔记关联的小部件信息 HashSet widgets = mNotesListAdapter.getSelectedWidget(); if (!isSyncMode()) { - // if not synced, delete notes directly + // 非同步模式：直接删除笔记 if (DataUtils.batchDeleteNotes(mContentResolver, mNotesListAdapter .getSelectedItemIds())) { + // 删除成功 } else { Log.e(TAG, "Delete notes error, should not happens"); } } else { - // in sync mode, we'll move the deleted note into the trash - // folder + // 同步模式：将笔记移动到垃圾箱文件夹（而不是直接删除） if (!DataUtils.batchMoveToFolder(mContentResolver, mNotesListAdapter .getSelectedItemIds(), Notes.ID_TRASH_FOLER)) { Log.e(TAG, "Move notes to trash folder error, should not happens"); } } - return widgets; + return widgets; // 返回小部件信息，用于后续更新 } @Override protected void onPostExecute(HashSet widgets) { + // 在UI线程执行，更新关联的小部件 if (widgets != null) { for (AppWidgetAttribute widget : widgets) { if (widget.widgetId != AppWidgetManager.INVALID_APPWIDGET_ID && widget.widgetType != Notes.TYPE_WIDGET_INVALIDE) { - updateWidget(widget.widgetId, widget.widgetType); + updateWidget(widget.widgetId, widget.widgetType); // 更新小部件 } } } + // 退出多选模式 mModeCallBack.finishActionMode(); } }.execute(); } + /** + * 删除文件夹 + * @param folderId 要删除的文件夹ID + */ private void deleteFolder(long folderId) { if (folderId == Notes.ID_ROOT_FOLDER) { Log.e(TAG, "Wrong folder id, should not happen " + folderId); @@ -514,15 +635,17 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt HashSet ids = new HashSet(); ids.add(folderId); + // 获取文件夹内笔记关联的小部件信息 HashSet widgets = DataUtils.getFolderNoteWidget(mContentResolver, folderId); if (!isSyncMode()) { - // if not synced, delete folder directly + // 非同步模式：直接删除文件夹 DataUtils.batchDeleteNotes(mContentResolver, ids); } else { - // in sync mode, we'll move the deleted folder into the trash folder + // 同步模式：将文件夹移动到垃圾箱 DataUtils.batchMoveToFolder(mContentResolver, ids, Notes.ID_TRASH_FOLER); } + // 更新关联的小部件 if (widgets != null) { for (AppWidgetAttribute widget : widgets) { if (widget.widgetId != AppWidgetManager.INVALID_APPWIDGET_ID @@ -533,40 +656,56 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt } } + /** + * 打开笔记（进入编辑界面） + * @param 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); + intent.setAction(Intent.ACTION_VIEW); // 设置动作为查看 + intent.putExtra(Intent.EXTRA_UID, data.getId()); // 传递笔记ID + this.startActivityForResult(intent, REQUEST_CODE_OPEN_NODE); // 启动笔记编辑活动 } + /** + * 打开文件夹（进入子文件夹） + * @param data 文件夹数据项 + */ private void openFolder(NoteItemData data) { - mCurrentFolderId = data.getId(); - startAsyncNotesListQuery(); + mCurrentFolderId = data.getId(); // 更新当前文件夹ID + startAsyncNotesListQuery(); // 重新查询该文件夹下的内容 + // 根据文件夹类型更新状态 if (data.getId() == Notes.ID_CALL_RECORD_FOLDER) { - mState = ListEditState.CALL_RECORD_FOLDER; - mAddNewNote.setVisibility(View.GONE); + mState = ListEditState.CALL_RECORD_FOLDER; // 通话记录文件夹 + mAddNewNote.setVisibility(View.GONE); // 隐藏新建笔记按钮（不能在通话记录文件夹新建笔记） } else { - mState = ListEditState.SUB_FOLDER; + mState = ListEditState.SUB_FOLDER; // 普通子文件夹 } + // 设置标题栏文本 if (data.getId() == Notes.ID_CALL_RECORD_FOLDER) { mTitleBar.setText(R.string.call_record_folder_name); } else { - mTitleBar.setText(data.getSnippet()); + mTitleBar.setText(data.getSnippet()); // 使用文件夹名称作为标题 } - mTitleBar.setVisibility(View.VISIBLE); + mTitleBar.setVisibility(View.VISIBLE); // 显示标题栏 } + /** + * 点击事件处理（OnClickListener接口方法） + */ public void onClick(View v) { switch (v.getId()) { case R.id.btn_new_note: - createNewNote(); + createNewNote(); // 点击新建笔记按钮 break; default: break; } } + /** + * 显示软键盘 + */ private void showSoftInput() { InputMethodManager inputMethodManager = (InputMethodManager) getSystemService(Context.INPUT_METHOD_SERVICE); if (inputMethodManager != null) { @@ -574,82 +713,100 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt } } + /** + * 隐藏软键盘 + * @param view 当前获得焦点的视图 + */ private void hideSoftInput(View view) { InputMethodManager inputMethodManager = (InputMethodManager) getSystemService(Context.INPUT_METHOD_SERVICE); inputMethodManager.hideSoftInputFromWindow(view.getWindowToken(), 0); } + /** + * 显示创建或修改文件夹的对话框 + * @param create true表示创建新文件夹，false表示修改现有文件夹名称 + */ 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); - showSoftInput(); + showSoftInput(); // 显示软键盘 + // 根据是创建还是修改设置不同的初始文本和标题 if (!create) { + // 修改文件夹名称 if (mFocusNoteDataItem != null) { - etName.setText(mFocusNoteDataItem.getSnippet()); + etName.setText(mFocusNoteDataItem.getSnippet()); // 设置当前文件夹名称为初始文本 builder.setTitle(getString(R.string.menu_folder_change_name)); } else { Log.e(TAG, "The long click data item is null"); return; } } else { - etName.setText(""); + // 创建新文件夹 + etName.setText(""); // 清空文本 builder.setTitle(this.getString(R.string.menu_create_folder)); } - builder.setPositiveButton(android.R.string.ok, null); + builder.setPositiveButton(android.R.string.ok, null); // 确定按钮（稍后设置监听器） builder.setNegativeButton(android.R.string.cancel, new DialogInterface.OnClickListener() { public void onClick(DialogInterface dialog, int which) { - hideSoftInput(etName); + hideSoftInput(etName); // 取消时隐藏软键盘 } }); + // 显示对话框并获取对话框实例 final Dialog dialog = builder.setView(view).show(); + // 获取确定按钮 final Button positive = (Button)dialog.findViewById(android.R.id.button1); positive.setOnClickListener(new OnClickListener() { public void onClick(View v) { - hideSoftInput(etName); - String name = etName.getText().toString(); + hideSoftInput(etName); // 隐藏软键盘 + String name = etName.getText().toString(); // 获取输入的文件夹名称 + // 检查文件夹名称是否已存在 if (DataUtils.checkVisibleFolderName(mContentResolver, name)) { Toast.makeText(NotesListActivity.this, getString(R.string.folder_exist, name), Toast.LENGTH_LONG).show(); - etName.setSelection(0, etName.length()); + etName.setSelection(0, etName.length()); // 选中全部文本，方便修改 return; } if (!create) { + // 修改现有文件夹名称 if (!TextUtils.isEmpty(name)) { ContentValues values = new ContentValues(); - values.put(NoteColumns.SNIPPET, name); + values.put(NoteColumns.SNIPPET, name); // 新名称 values.put(NoteColumns.TYPE, Notes.TYPE_FOLDER); - values.put(NoteColumns.LOCAL_MODIFIED, 1); + values.put(NoteColumns.LOCAL_MODIFIED, 1); // 标记为本地已修改（用于同步） mContentResolver.update(Notes.CONTENT_NOTE_URI, values, NoteColumns.ID + "=?", new String[] { - String.valueOf(mFocusNoteDataItem.getId()) + String.valueOf(mFocusNoteDataItem.getId()) // 更新指定ID的文件夹 }); } } else if (!TextUtils.isEmpty(name)) { + // 创建新文件夹 ContentValues values = new ContentValues(); - values.put(NoteColumns.SNIPPET, name); + values.put(NoteColumns.SNIPPET, name); // 文件夹名称 values.put(NoteColumns.TYPE, Notes.TYPE_FOLDER); - mContentResolver.insert(Notes.CONTENT_NOTE_URI, values); + mContentResolver.insert(Notes.CONTENT_NOTE_URI, values); // 插入新记录 } - dialog.dismiss(); + dialog.dismiss(); // 关闭对话框 } }); + // 初始时如果文本为空，禁用确定按钮 if (TextUtils.isEmpty(etName.getText())) { positive.setEnabled(false); } /** - * When the name edit text is null, disable the positive button + * 当名称编辑框文本为空时，禁用确定按钮 */ 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) { + // 根据文本是否为空启用或禁用确定按钮 if (TextUtils.isEmpty(etName.getText())) { positive.setEnabled(false); } else { @@ -659,28 +816,33 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt public void afterTextChanged(Editable s) { // TODO Auto-generated method stub - } }); } + /** + * 处理返回键按下事件 + */ @Override public void onBackPressed() { switch (mState) { case SUB_FOLDER: + // 在子文件夹内：返回根目录 mCurrentFolderId = Notes.ID_ROOT_FOLDER; mState = ListEditState.NOTE_LIST; - startAsyncNotesListQuery(); - mTitleBar.setVisibility(View.GONE); + startAsyncNotesListQuery(); // 重新查询根目录内容 + mTitleBar.setVisibility(View.GONE); // 隐藏标题栏 break; case CALL_RECORD_FOLDER: + // 在通话记录文件夹内：返回根目录 mCurrentFolderId = Notes.ID_ROOT_FOLDER; mState = ListEditState.NOTE_LIST; - mAddNewNote.setVisibility(View.VISIBLE); - mTitleBar.setVisibility(View.GONE); + mAddNewNote.setVisibility(View.VISIBLE); // 显示新建笔记按钮 + mTitleBar.setVisibility(View.GONE); // 隐藏标题栏 startAsyncNotesListQuery(); break; case NOTE_LIST: + // 在根目录：执行默认的返回操作（退出应用） super.onBackPressed(); break; default: @@ -688,8 +850,14 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt } } + /** + * 更新桌面小部件 + * @param appWidgetId 小部件ID + * @param 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); } else if (appWidgetType == Notes.TYPE_WIDGET_4X) { @@ -699,33 +867,43 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt return; } + // 设置要更新的小部件ID intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_IDS, new int[] { - appWidgetId + appWidgetId }); - sendBroadcast(intent); - setResult(RESULT_OK, intent); + sendBroadcast(intent); // 发送广播更新小部件 + setResult(RESULT_OK, intent); // 设置活动结果 } + /** + * 文件夹的上下文菜单创建监听器（长按文件夹时弹出） + */ private final OnCreateContextMenuListener mFolderOnCreateContextMenuListener = new OnCreateContextMenuListener() { public void onCreateContextMenu(ContextMenu menu, View v, ContextMenuInfo menuInfo) { if (mFocusNoteDataItem != null) { - menu.setHeaderTitle(mFocusNoteDataItem.getSnippet()); - menu.add(0, MENU_FOLDER_VIEW, 0, R.string.menu_folder_view); - menu.add(0, MENU_FOLDER_DELETE, 0, R.string.menu_folder_delete); - menu.add(0, MENU_FOLDER_CHANGE_NAME, 0, R.string.menu_folder_change_name); + menu.setHeaderTitle(mFocusNoteDataItem.getSnippet()); // 设置菜单标题为文件夹名称 + menu.add(0, MENU_FOLDER_VIEW, 0, R.string.menu_folder_view); // 查看文件夹 + menu.add(0, MENU_FOLDER_DELETE, 0, R.string.menu_folder_delete); // 删除文件夹 + menu.add(0, MENU_FOLDER_CHANGE_NAME, 0, R.string.menu_folder_change_name); // 修改名称 } } }; + /** + * 上下文菜单关闭时调用 + */ @Override public void onContextMenuClosed(Menu menu) { if (mNotesListView != null) { - mNotesListView.setOnCreateContextMenuListener(null); + mNotesListView.setOnCreateContextMenuListener(null); // 移除上下文菜单监听器 } super.onContextMenuClosed(menu); } + /** + * 处理上下文菜单项选择 + */ @Override public boolean onContextItemSelected(MenuItem item) { if (mFocusNoteDataItem == null) { @@ -734,9 +912,10 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt } switch (item.getItemId()) { case MENU_FOLDER_VIEW: - openFolder(mFocusNoteDataItem); + openFolder(mFocusNoteDataItem); // 打开文件夹 break; 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); @@ -744,73 +923,81 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt builder.setPositiveButton(android.R.string.ok, new DialogInterface.OnClickListener() { public void onClick(DialogInterface dialog, int which) { - deleteFolder(mFocusNoteDataItem.getId()); + deleteFolder(mFocusNoteDataItem.getId()); // 执行删除 } }); builder.setNegativeButton(android.R.string.cancel, null); builder.show(); break; case MENU_FOLDER_CHANGE_NAME: - showCreateOrModifyFolderDialog(false); + showCreateOrModifyFolderDialog(false); // 显示修改名称对话框 break; default: break; } - return true; } + /** + * 准备选项菜单（每次打开菜单时调用） + */ @Override public boolean onPrepareOptionsMenu(Menu menu) { - menu.clear(); + menu.clear(); // 清空现有菜单项 + // 根据当前状态加载不同的菜单 if (mState == ListEditState.NOTE_LIST) { - getMenuInflater().inflate(R.menu.note_list, menu); - // set sync or sync_cancel + getMenuInflater().inflate(R.menu.note_list, menu); // 根目录菜单 + // 设置同步或取消同步菜单项标题 menu.findItem(R.id.menu_sync).setTitle( GTaskSyncService.isSyncing() ? R.string.menu_sync_cancel : R.string.menu_sync); } else if (mState == ListEditState.SUB_FOLDER) { - getMenuInflater().inflate(R.menu.sub_folder, menu); + getMenuInflater().inflate(R.menu.sub_folder, menu); // 子文件夹菜单 } else if (mState == ListEditState.CALL_RECORD_FOLDER) { - getMenuInflater().inflate(R.menu.call_record_folder, menu); + getMenuInflater().inflate(R.menu.call_record_folder, menu); // 通话记录文件夹菜单 } else { Log.e(TAG, "Wrong state:" + mState); } return true; } + /** + * 处理选项菜单项点击 + */ @Override public boolean onOptionsItemSelected(MenuItem item) { switch (item.getItemId()) { case R.id.menu_new_folder: { - showCreateOrModifyFolderDialog(true); + showCreateOrModifyFolderDialog(true); // 创建新文件夹 break; } case R.id.menu_export_text: { - exportNoteToText(); + exportNoteToText(); // 导出笔记为文本文件 break; } case R.id.menu_sync: { if (isSyncMode()) { + // 同步模式：根据当前状态执行同步或取消同步 if (TextUtils.equals(item.getTitle(), getString(R.string.menu_sync))) { - GTaskSyncService.startSync(this); + GTaskSyncService.startSync(this); // 开始同步 } else { - GTaskSyncService.cancelSync(this); + GTaskSyncService.cancelSync(this); // 取消同步 } } else { + // 非同步模式：跳转到设置界面 startPreferenceActivity(); } break; } case R.id.menu_setting: { - startPreferenceActivity(); + startPreferenceActivity(); // 跳转到设置界面 break; } case R.id.menu_new_note: { - createNewNote(); + createNewNote(); // 新建笔记（在子文件夹菜单中） break; } case R.id.menu_search: - onSearchRequested(); + onSearchRequested(); // 触发搜索 break; default: break; @@ -818,24 +1005,32 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt return true; } + /** + * 处理搜索请求 + */ @Override public boolean onSearchRequested() { startSearch(null, false, null /* appData */, false); return true; } + /** + * 将笔记导出为文本文件 + */ private void exportNoteToText() { final BackupUtils backup = BackupUtils.getInstance(NotesListActivity.this); + // 使用AsyncTask在后台执行导出操作 new AsyncTask() { - @Override protected Integer doInBackground(Void... unused) { - return backup.exportToText(); + return backup.exportToText(); // 执行导出 } @Override protected void onPostExecute(Integer result) { + // 在UI线程显示导出结果 if (result == BackupUtils.STATE_SD_CARD_UNMOUONTED) { + // SD卡未挂载 AlertDialog.Builder builder = new AlertDialog.Builder(NotesListActivity.this); builder.setTitle(NotesListActivity.this .getString(R.string.failed_sdcard_export)); @@ -844,6 +1039,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); builder.setTitle(NotesListActivity.this .getString(R.string.success_sdcard_export)); @@ -853,6 +1049,7 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt builder.setPositiveButton(android.R.string.ok, null); builder.show(); } 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)); @@ -862,47 +1059,63 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt builder.show(); } } - }.execute(); } + /** + * 判断是否处于同步模式（是否设置了同步账户） + */ private boolean isSyncMode() { return NotesPreferenceActivity.getSyncAccountName(this).trim().length() > 0; } + /** + * 启动设置活动 + */ 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 { - public void onItemClick(AdapterView parent, View view, int position, long id) { + // 检查点击的视图是否是NotesListItem（我们的自定义列表项视图） if (view instanceof NotesListItem) { - NoteItemData item = ((NotesListItem) view).getItemData(); + NoteItemData item = ((NotesListItem) view).getItemData(); // 获取对应的数据项 + + // 如果当前处于多选模式 if (mNotesListAdapter.isInChoiceMode()) { + // 只允许选择笔记（不能选择文件夹） if (item.getType() == Notes.TYPE_NOTE) { + // 调整位置（考虑头部视图） position = position - mNotesListView.getHeaderViewsCount(); + // 切换选中状态 mModeCallBack.onItemCheckedStateChanged(null, position, id, !mNotesListAdapter.isSelectedItem(position)); } - return; + return; // 在多选模式下不执行其他操作 } + // 根据当前状态处理点击 switch (mState) { case NOTE_LIST: + // 根目录下：点击文件夹则打开，点击笔记则编辑 if (item.getType() == Notes.TYPE_FOLDER || item.getType() == Notes.TYPE_SYSTEM) { - openFolder(item); + openFolder(item); // 打开文件夹 } else if (item.getType() == Notes.TYPE_NOTE) { - openNode(item); + openNode(item); // 打开笔记 } else { Log.e(TAG, "Wrong note type in NOTE_LIST"); } break; case SUB_FOLDER: case CALL_RECORD_FOLDER: + // 在文件夹内：只能点击笔记进行编辑 if (item.getType() == Notes.TYPE_NOTE) { openNode(item); } else { @@ -914,13 +1127,17 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt } } } - } + /** + * 开始查询可用的目标文件夹（用于移动操作） + */ 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 + ")"; + "(" + selection + ") OR (" + NoteColumns.ID + "=" + Notes.ID_ROOT_FOLDER + ")"; mBackgroundQueryHandler.startQuery(FOLDER_LIST_QUERY_TOKEN, null, @@ -928,27 +1145,34 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt FoldersListAdapter.PROJECTION, selection, new String[] { - String.valueOf(Notes.TYPE_FOLDER), - String.valueOf(Notes.ID_TRASH_FOLER), - String.valueOf(mCurrentFolderId) + String.valueOf(Notes.TYPE_FOLDER), // 类型：文件夹 + String.valueOf(Notes.ID_TRASH_FOLER), // 排除垃圾箱 + String.valueOf(mCurrentFolderId) // 排除当前文件夹 }, - NoteColumns.MODIFIED_DATE + " DESC"); + NoteColumns.MODIFIED_DATE + " DESC"); // 按修改日期降序排序 } + /** + * 列表项长按监听器（OnItemLongClickListener接口方法） + */ public boolean onItemLongClick(AdapterView parent, View view, int position, long id) { if (view instanceof NotesListItem) { - mFocusNoteDataItem = ((NotesListItem) view).getItemData(); + mFocusNoteDataItem = ((NotesListItem) view).getItemData(); // 记录长按的数据项 + // 如果长按的是笔记且不在多选模式下，启动多选模式 if (mFocusNoteDataItem.getType() == Notes.TYPE_NOTE && !mNotesListAdapter.isInChoiceMode()) { if (mNotesListView.startActionMode(mModeCallBack) != null) { + // 启动成功，设置当前项为选中状态 mModeCallBack.onItemCheckedStateChanged(null, position, id, true); + // 提供触觉反馈（震动） mNotesListView.performHapticFeedback(HapticFeedbackConstants.LONG_PRESS); } else { Log.e(TAG, "startActionMode fails"); } } else if (mFocusNoteDataItem.getType() == Notes.TYPE_FOLDER) { + // 如果长按的是文件夹，设置上下文菜单监听器 mNotesListView.setOnCreateContextMenuListener(mFolderOnCreateContextMenuListener); } } - return false; + return false; // 返回false，让系统继续处理长按事件（显示上下文菜单等） } -} +} \ No newline at end of file diff --git a/src/notes/ui/NotesListAdapter.java b/src/notes/ui/NotesListAdapter.java index 51c9cb9..44bfb13 100644 --- a/src/notes/ui/NotesListAdapter.java +++ b/src/notes/ui/NotesListAdapter.java @@ -30,58 +30,110 @@ import java.util.HashMap; import java.util.HashSet; import java.util.Iterator; - +/** + * 笔记列表适配器，用于管理笔记列表的显示和多选操作 + * 继承自CursorAdapter，专门处理数据库游标数据 + */ public class NotesListAdapter extends CursorAdapter { private static final String TAG = "NotesListAdapter"; - private Context mContext; + private Context mContext; // 上下文对象 + // 存储选中状态的映射表，key为位置索引，value为是否选中 private HashMap mSelectedIndex; - private int mNotesCount; - private boolean mChoiceMode; + private int mNotesCount; // 笔记总数（不包括文件夹） + private boolean mChoiceMode; // 标记是否处于多选模式 + /** + * 小部件属性内部类，用于存储笔记关联的桌面小部件信息 + */ public static class AppWidgetAttribute { - public int widgetId; - public int widgetType; + public int widgetId; // 小部件的唯一标识ID + public int widgetType; // 小部件的类型（如2x2、4x4等） }; + /** + * 构造函数 + * @param context 上下文环境 + */ public NotesListAdapter(Context context) { - super(context, null); - mSelectedIndex = new HashMap(); + super(context, null); // 调用父类构造函数，初始游标为null + mSelectedIndex = new HashMap(); // 初始化选中状态记录表 mContext = context; - mNotesCount = 0; + mNotesCount = 0; // 初始笔记数量为0 } + /** + * 创建新的列表项视图 + * @param context 上下文环境 + * @param cursor 数据库游标 + * @param parent 父视图容器 + * @return 新创建的笔记列表项视图 + */ @Override public View newView(Context context, Cursor cursor, ViewGroup parent) { + // 创建自定义的笔记列表项视图 return new NotesListItem(context); } + /** + * 将数据绑定到已有的列表项视图 + * @param view 要绑定数据的视图 + * @param context 上下文环境 + * @param cursor 数据库游标 + */ @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, isSelectedItem(cursor.getPosition())); } } + /** + * 设置指定位置的选中状态 + * @param position 列表中的位置索引 + * @param checked 是否选中（true为选中，false为取消选中） + */ public void setCheckedItem(final int position, final boolean checked) { + // 更新选中状态映射表 mSelectedIndex.put(position, checked); + // 通知数据发生变化，需要刷新列表显示 notifyDataSetChanged(); } + /** + * 检查当前是否处于多选模式 + * @return 如果处于多选模式返回true，否则返回false + */ public boolean isInChoiceMode() { return mChoiceMode; } + /** + * 设置多选模式开关 + * @param mode true进入多选模式，false退出多选模式 + */ public void setChoiceMode(boolean mode) { + // 清空所有选中状态记录 mSelectedIndex.clear(); mChoiceMode = mode; } + /** + * 全选或取消全选所有笔记（不包括文件夹） + * @param checked true全选所有笔记，false取消全选 + */ 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); } @@ -89,14 +141,24 @@ public class NotesListAdapter extends CursorAdapter { } } + /** + * 获取所有选中项的ID集合 + * @return 包含选中项ID的集合 + */ public HashSet getSelectedItemIds() { + // 创建ID集合 HashSet itemSet = new HashSet(); + // 遍历所有记录的位置 for (Integer position : mSelectedIndex.keySet()) { + // 检查该位置是否被选中 if (mSelectedIndex.get(position) == true) { + // 获取该项的笔记ID Long id = getItemId(position); + // 安全检查：确保不是根文件夹的ID if (id == Notes.ID_ROOT_FOLDER) { Log.d(TAG, "Wrong item id, should not happen"); } else { + // 将有效ID添加到集合中 itemSet.add(id); } } @@ -105,19 +167,30 @@ public class NotesListAdapter extends CursorAdapter { return itemSet; } + /** + * 获取所有选中项关联的小部件属性 + * @return 小部件属性集合，用于更新桌面小部件 + */ public HashSet getSelectedWidget() { + // 创建小部件属性集合 HashSet itemSet = new HashSet(); + // 遍历所有选中项 for (Integer position : mSelectedIndex.keySet()) { if (mSelectedIndex.get(position) == true) { + // 获取对应位置的数据游标 Cursor c = (Cursor) getItem(position); if (c != null) { + // 创建小部件属性对象 AppWidgetAttribute widget = new AppWidgetAttribute(); + // 从游标数据创建笔记对象 NoteItemData item = new NoteItemData(mContext, c); + // 设置小部件属性 widget.widgetId = item.getWidgetId(); widget.widgetType = item.getWidgetType(); itemSet.add(widget); /** - * Don't close cursor here, only the adapter could close it + * 重要：不要在这里关闭游标！ + * 游标由适配器统一管理，外部关闭会导致适配器出错 */ } else { Log.e(TAG, "Invalid cursor"); @@ -128,14 +201,21 @@ public class NotesListAdapter extends CursorAdapter { return itemSet; } + /** + * 获取选中项的数量 + * @return 选中项的数量 + */ public int getSelectedCount() { + // 获取所有选中状态值 Collection values = mSelectedIndex.values(); if (null == values) { return 0; } + // 使用迭代器遍历统计选中数量 Iterator iter = values.iterator(); int count = 0; while (iter.hasNext()) { + // 如果状态为true，计数加1 if (true == iter.next()) { count++; } @@ -143,37 +223,65 @@ public class NotesListAdapter extends CursorAdapter { return count; } + /** + * 检查是否所有笔记都已被选中 + * @return 如果全部选中返回true，否则返回false + */ public boolean isAllSelected() { + // 获取当前选中数量 int checkedCount = getSelectedCount(); + // 全选条件：选中数量等于笔记总数且不为0 return (checkedCount != 0 && checkedCount == mNotesCount); } + /** + * 检查指定位置是否被选中 + * @param position 要检查的位置 + * @return 如果选中返回true，否则返回false + */ public boolean isSelectedItem(final int position) { + // 如果映射表中没有该位置的记录，说明未选中 if (null == mSelectedIndex.get(position)) { return false; } return mSelectedIndex.get(position); } + /** + * 当数据内容发生变化时自动调用 + */ @Override protected void onContentChanged() { super.onContentChanged(); + // 重新计算笔记数量 calcNotesCount(); } + /** + * 更换数据游标时调用 + * @param cursor 新的数据游标 + */ @Override public void changeCursor(Cursor cursor) { super.changeCursor(cursor); + // 重新计算笔记数量 calcNotesCount(); } + /** + * 计算当前列表中笔记（非文件夹）的总数量 + * 这个方法用于支持全选功能的状态判断 + */ private void calcNotesCount() { - mNotesCount = 0; + mNotesCount = 0; // 重置计数器 + // 遍历所有列表项 for (int i = 0; i < getCount(); i++) { + // 获取指定位置的数据 Cursor c = (Cursor) getItem(i); if (c != null) { + // 只统计笔记类型，排除文件夹 if (NoteItemData.getNoteType(c) == Notes.TYPE_NOTE) { - mNotesCount++; + mNotesCount++; // 笔记数量加1 } } else { Log.e(TAG, "Invalid cursor"); @@ -181,4 +289,4 @@ public class NotesListAdapter extends CursorAdapter { } } } -} +} \ No newline at end of file diff --git a/src/notes/ui/NotesListItem.java b/src/notes/ui/NotesListItem.java index 1221e80..52a530e 100644 --- a/src/notes/ui/NotesListItem.java +++ b/src/notes/ui/NotesListItem.java @@ -29,94 +29,143 @@ import net.micode.notes.data.Notes; import net.micode.notes.tool.DataUtils; import net.micode.notes.tool.ResourceParser.NoteItemBgResources; - +/** + * 笔记列表项自定义视图，用于显示单个笔记或文件夹项 + * 继承自LinearLayout，包含标题、时间、提醒图标等子视图 + */ 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; // 多选模式下的复选框 + /** + * 构造函数 + * @param context 上下文环境 + */ public NotesListItem(Context context) { super(context); + // 从布局文件加载视图 inflate(context, R.layout.note_item, this); + // 初始化各个子视图组件 mAlert = (ImageView) findViewById(R.id.iv_alert_icon); mTitle = (TextView) findViewById(R.id.tv_title); mTime = (TextView) findViewById(R.id.tv_time); mCallName = (TextView) findViewById(R.id.tv_name); + // 使用系统预定义的checkbox ID mCheckBox = (CheckBox) findViewById(android.R.id.checkbox); } + /** + * 将数据绑定到视图上，根据数据类型和状态显示不同的UI + * @param context 上下文环境 + * @param data 笔记或文件夹数据 + * @param choiceMode 是否处于多选模式 + * @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); } else { + // 非多选模式或文件夹类型：隐藏复选框 mCheckBox.setVisibility(View.GONE); } + // 保存数据引用 mItemData = data; + + // 根据数据类型显示不同的UI布局 if (data.getId() == Notes.ID_CALL_RECORD_FOLDER) { - mCallName.setVisibility(View.GONE); - mAlert.setVisibility(View.VISIBLE); - mTitle.setTextAppearance(context, R.style.TextAppearancePrimaryItem); + // 通话记录文件夹的特殊显示 + mCallName.setVisibility(View.GONE); // 隐藏联系人姓名 + mAlert.setVisibility(View.VISIBLE); // 显示图标 + mTitle.setTextAppearance(context, R.style.TextAppearancePrimaryItem); // 设置主文本样式 + // 设置文件夹名称和文件数量显示 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); + mAlert.setImageResource(R.drawable.call_record); // 设置通话记录图标 } else if (data.getParentId() == Notes.ID_CALL_RECORD_FOLDER) { - mCallName.setVisibility(View.VISIBLE); - mCallName.setText(data.getCallName()); - mTitle.setTextAppearance(context,R.style.TextAppearanceSecondaryItem); - mTitle.setText(DataUtils.getFormattedSnippet(data.getSnippet())); + // 通话记录笔记的特殊显示 + mCallName.setVisibility(View.VISIBLE); // 显示联系人姓名 + mCallName.setText(data.getCallName()); // 设置联系人姓名 + mTitle.setTextAppearance(context,R.style.TextAppearanceSecondaryItem); // 设置次文本样式 + mTitle.setText(DataUtils.getFormattedSnippet(data.getSnippet())); // 设置格式化后的内容摘要 + // 根据是否有提醒设置提醒图标 if (data.hasAlert()) { - mAlert.setImageResource(R.drawable.clock); + mAlert.setImageResource(R.drawable.clock); // 时钟图标 mAlert.setVisibility(View.VISIBLE); } else { mAlert.setVisibility(View.GONE); } } else { - mCallName.setVisibility(View.GONE); - mTitle.setTextAppearance(context, R.style.TextAppearancePrimaryItem); + // 普通笔记或文件夹的显示 + mCallName.setVisibility(View.GONE); // 隐藏联系人姓名 + mTitle.setTextAppearance(context, R.style.TextAppearancePrimaryItem); // 设置主文本样式 if (data.getType() == Notes.TYPE_FOLDER) { + // 文件夹显示：名称 + 文件数量 mTitle.setText(data.getSnippet() + context.getString(R.string.format_folder_files_count, - data.getNotesCount())); - mAlert.setVisibility(View.GONE); + data.getNotesCount())); + mAlert.setVisibility(View.GONE); // 文件夹不显示提醒图标 } else { + // 普通笔记显示：内容摘要 mTitle.setText(DataUtils.getFormattedSnippet(data.getSnippet())); + // 根据是否有提醒设置提醒图标 if (data.hasAlert()) { - mAlert.setImageResource(R.drawable.clock); + mAlert.setImageResource(R.drawable.clock); // 时钟图标 mAlert.setVisibility(View.VISIBLE); } else { mAlert.setVisibility(View.GONE); } } } + + // 设置相对时间显示（如"2分钟前"、"昨天"等） mTime.setText(DateUtils.getRelativeTimeSpanString(data.getModifiedDate())); + // 根据位置和类型设置背景 setBackground(data); } + /** + * 根据数据项的位置和类型设置不同的背景 + * 实现列表项的分组视觉效果（第一个、最后一个、中间项等） + * @param data 笔记数据项 + */ private void setBackground(NoteItemData data) { - int id = data.getBgColorId(); + int id = data.getBgColorId(); // 获取背景颜色ID if (data.getType() == Notes.TYPE_NOTE) { + // 笔记类型的背景设置 if (data.isSingle() || data.isOneFollowingFolder()) { + // 单个笔记或紧跟在文件夹后的单个笔记：单一样式背景 setBackgroundResource(NoteItemBgResources.getNoteBgSingleRes(id)); } else if (data.isLast()) { + // 列表中的最后一个笔记：底部样式背景 setBackgroundResource(NoteItemBgResources.getNoteBgLastRes(id)); } else if (data.isFirst() || data.isMultiFollowingFolder()) { + // 列表中的第一个笔记或多个紧跟在文件夹后的笔记：顶部样式背景 setBackgroundResource(NoteItemBgResources.getNoteBgFirstRes(id)); } else { + // 中间位置的笔记：普通样式背景 setBackgroundResource(NoteItemBgResources.getNoteBgNormalRes(id)); } } else { + // 文件夹类型的背景：统一使用文件夹背景 setBackgroundResource(NoteItemBgResources.getFolderBgRes()); } } + /** + * 获取当前绑定的数据对象 + * @return NoteItemData对象 + */ public NoteItemData getItemData() { return mItemData; } -} +} \ No newline at end of file diff --git a/src/notes/ui/NotesPreferenceActivity.java b/src/notes/ui/NotesPreferenceActivity.java index 07c5f7e..f67f37b 100644 --- a/src/notes/ui/NotesPreferenceActivity.java +++ b/src/notes/ui/NotesPreferenceActivity.java @@ -47,55 +47,67 @@ import net.micode.notes.data.Notes; import net.micode.notes.data.Notes.NoteColumns; import net.micode.notes.gtask.remote.GTaskSyncService; - +/** + * 笔记应用的设置活动，用于管理同步账户和偏好设置 + * 继承自PreferenceActivity，提供Google任务同步功能配置 + */ 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; - - private GTaskReceiver mReceiver; - - private Account[] mOriAccounts; - - private boolean mHasAddedAccount; + private PreferenceCategory mAccountCategory; // 账户设置分类 + private GTaskReceiver mReceiver; // 同步服务广播接收器 + private Account[] mOriAccounts; // 原始账户列表 + private boolean mHasAddedAccount; // 标记是否添加了新账户 + /** + * Activity创建时的初始化方法 + */ @Override protected void onCreate(Bundle icicle) { super.onCreate(icicle); - /* using the app icon for navigation */ + // 在ActionBar中显示返回按钮 getActionBar().setDisplayHomeAsUpEnabled(true); + // 从XML资源加载偏好设置 addPreferencesFromResource(R.xml.preferences); + // 查找账户设置分类 mAccountCategory = (PreferenceCategory) findPreference(PREFERENCE_SYNC_ACCOUNT_KEY); + // 创建广播接收器监听同步状态变化 mReceiver = new GTaskReceiver(); IntentFilter filter = new IntentFilter(); filter.addAction(GTaskSyncService.GTASK_SERVICE_BROADCAST_NAME); registerReceiver(mReceiver, filter); mOriAccounts = null; + // 加载设置页面的自定义头部布局 View header = LayoutInflater.from(this).inflate(R.layout.settings_header, null); getListView().addHeaderView(header, null, true); } + /** + * Activity恢复时调用，处理账户变化 + */ @Override protected void onResume() { super.onResume(); - // need to set sync account automatically if user has added a new - // account + // 如果用户添加了新账户，自动设置同步账户 if (mHasAddedAccount) { Account[] accounts = getGoogleAccounts(); + // 比较新旧账户列表，找到新添加的账户 if (mOriAccounts != null && accounts.length > mOriAccounts.length) { for (Account accountNew : accounts) { boolean found = false; @@ -106,6 +118,7 @@ public class NotesPreferenceActivity extends PreferenceActivity { } } if (!found) { + // 设置新账户为同步账户 setSyncAccount(accountNew.name); break; } @@ -113,9 +126,13 @@ public class NotesPreferenceActivity extends PreferenceActivity { } } + // 刷新界面显示 refreshUI(); } + /** + * Activity销毁时清理资源 + */ @Override protected void onDestroy() { if (mReceiver != null) { @@ -124,8 +141,11 @@ public class NotesPreferenceActivity extends PreferenceActivity { super.onDestroy(); } + /** + * 加载账户设置项 + */ private void loadAccountPreference() { - mAccountCategory.removeAll(); + mAccountCategory.removeAll(); // 清空现有设置项 Preference accountPref = new Preference(this); final String defaultAccount = getSyncAccountName(this); @@ -133,18 +153,18 @@ public class NotesPreferenceActivity extends PreferenceActivity { accountPref.setSummary(getString(R.string.preferences_account_summary)); accountPref.setOnPreferenceClickListener(new OnPreferenceClickListener() { public boolean onPreferenceClick(Preference preference) { + // 检查是否正在同步，同步过程中不允许修改账户 if (!GTaskSyncService.isSyncing()) { if (TextUtils.isEmpty(defaultAccount)) { - // the first time to set account + // 首次设置账户，显示选择账户对话框 showSelectAccountAlertDialog(); } else { - // if the account has already been set, we need to promp - // user about the risk + // 已设置过账户，显示确认对话框 showChangeAccountConfirmAlertDialog(); } } else { Toast.makeText(NotesPreferenceActivity.this, - R.string.preferences_toast_cannot_change_account, Toast.LENGTH_SHORT) + R.string.preferences_toast_cannot_change_account, Toast.LENGTH_SHORT) .show(); } return true; @@ -154,11 +174,14 @@ 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); - // set button state + // 根据同步状态设置按钮文本和点击事件 if (GTaskSyncService.isSyncing()) { syncButton.setText(getString(R.string.preferences_button_sync_cancel)); syncButton.setOnClickListener(new View.OnClickListener() { @@ -174,33 +197,44 @@ public class NotesPreferenceActivity extends PreferenceActivity { } }); } + // 只有设置了同步账户才能启用同步按钮 syncButton.setEnabled(!TextUtils.isEmpty(getSyncAccountName(this))); - // set last sync time + // 设置最后同步时间显示 if (GTaskSyncService.isSyncing()) { + // 显示同步进度 lastSyncTimeView.setText(GTaskSyncService.getProgressString()); lastSyncTimeView.setVisibility(View.VISIBLE); } else { long lastSyncTime = getLastSyncTime(this); if (lastSyncTime != 0) { + // 格式化显示最后同步时间 lastSyncTimeView.setText(getString(R.string.preferences_last_sync_time, DateFormat.format(getString(R.string.preferences_last_sync_time_format), lastSyncTime))); lastSyncTimeView.setVisibility(View.VISIBLE); } else { + // 从未同步过，隐藏时间显示 lastSyncTimeView.setVisibility(View.GONE); } } } + /** + * 刷新整个界面 + */ private void refreshUI() { loadAccountPreference(); loadSyncButton(); } + /** + * 显示选择账户对话框 + */ private void showSelectAccountAlertDialog() { AlertDialog.Builder dialogBuilder = new AlertDialog.Builder(this); + // 设置自定义标题布局 View titleView = LayoutInflater.from(this).inflate(R.layout.account_dialog_title, null); TextView titleTextView = (TextView) titleView.findViewById(R.id.account_dialog_title); titleTextView.setText(getString(R.string.preferences_dialog_select_account_title)); @@ -208,45 +242,49 @@ public class NotesPreferenceActivity extends PreferenceActivity { subtitleTextView.setText(getString(R.string.preferences_dialog_select_account_tips)); dialogBuilder.setCustomTitle(titleView); - dialogBuilder.setPositiveButton(null, null); + dialogBuilder.setPositiveButton(null, null); // 不显示确定按钮 Account[] accounts = getGoogleAccounts(); String defAccount = getSyncAccountName(this); - mOriAccounts = accounts; - mHasAddedAccount = false; + mOriAccounts = accounts; // 保存当前账户列表 + mHasAddedAccount = false; // 重置添加账户标记 if (accounts.length > 0) { + // 创建账户选择列表 CharSequence[] items = new CharSequence[accounts.length]; final CharSequence[] itemMapping = items; int checkedItem = -1; int index = 0; for (Account account : accounts) { if (TextUtils.equals(account.name, defAccount)) { - checkedItem = index; + checkedItem = index; // 标记当前选中的账户 } items[index++] = account.name; } dialogBuilder.setSingleChoiceItems(items, checkedItem, new DialogInterface.OnClickListener() { public void onClick(DialogInterface dialog, int which) { + // 用户选择账户后设置同步账户 setSyncAccount(itemMapping[which].toString()); dialog.dismiss(); - refreshUI(); + refreshUI(); // 刷新界面 } }); } + // 添加"添加账户"选项 View addAccountView = LayoutInflater.from(this).inflate(R.layout.add_account_text, null); dialogBuilder.setView(addAccountView); final AlertDialog dialog = dialogBuilder.show(); addAccountView.setOnClickListener(new View.OnClickListener() { public void onClick(View v) { - mHasAddedAccount = true; + mHasAddedAccount = true; // 标记正在添加账户 + // 启动系统添加账户界面 Intent intent = new Intent("android.settings.ADD_ACCOUNT_SETTINGS"); intent.putExtra(AUTHORITIES_FILTER_KEY, new String[] { - "gmail-ls" + "gmail-ls" // 限制只显示Gmail账户 }); startActivityForResult(intent, -1); dialog.dismiss(); @@ -254,17 +292,21 @@ public class NotesPreferenceActivity extends PreferenceActivity { }); } + /** + * 显示更改账户确认对话框 + */ private void showChangeAccountConfirmAlertDialog() { AlertDialog.Builder dialogBuilder = new AlertDialog.Builder(this); View titleView = LayoutInflater.from(this).inflate(R.layout.account_dialog_title, null); TextView titleTextView = (TextView) titleView.findViewById(R.id.account_dialog_title); titleTextView.setText(getString(R.string.preferences_dialog_change_account_title, - getSyncAccountName(this))); + getSyncAccountName(this))); // 显示当前账户名 TextView subtitleTextView = (TextView) titleView.findViewById(R.id.account_dialog_subtitle); subtitleTextView.setText(getString(R.string.preferences_dialog_change_account_warn_msg)); dialogBuilder.setCustomTitle(titleView); + // 提供三个操作选项：更改账户、移除账户、取消 CharSequence[] menuItemArray = new CharSequence[] { getString(R.string.preferences_menu_change_account), getString(R.string.preferences_menu_remove_account), @@ -273,22 +315,32 @@ public class NotesPreferenceActivity extends PreferenceActivity { dialogBuilder.setItems(menuItemArray, new DialogInterface.OnClickListener() { public void onClick(DialogInterface dialog, int which) { if (which == 0) { + // 更改账户 showSelectAccountAlertDialog(); } else if (which == 1) { + // 移除账户 removeSyncAccount(); refreshUI(); } + // which == 2 取消操作，不做任何事 } }); dialogBuilder.show(); } + /** + * 获取设备上的Google账户列表 + */ private Account[] getGoogleAccounts() { AccountManager accountManager = AccountManager.get(this); - return accountManager.getAccountsByType("com.google"); + return accountManager.getAccountsByType("com.google"); // Google账户类型 } + /** + * 设置同步账户 + */ private void setSyncAccount(String account) { + // 只有当账户发生变化时才更新 if (!getSyncAccountName(this).equals(account)) { SharedPreferences settings = getSharedPreferences(PREFERENCE_NAME, Context.MODE_PRIVATE); SharedPreferences.Editor editor = settings.edit(); @@ -299,15 +351,15 @@ public class NotesPreferenceActivity extends PreferenceActivity { } editor.commit(); - // clean up last sync time + // 重置最后同步时间 setLastSyncTime(this, 0); - // clean up local gtask related info + // 在新线程中清理本地同步信息 new Thread(new Runnable() { public void run() { ContentValues values = new ContentValues(); - values.put(NoteColumns.GTASK_ID, ""); - values.put(NoteColumns.SYNC_ID, 0); + values.put(NoteColumns.GTASK_ID, ""); // 清空任务ID + values.put(NoteColumns.SYNC_ID, 0); // 重置同步ID getContentResolver().update(Notes.CONTENT_NOTE_URI, values, null, null); } }).start(); @@ -318,9 +370,13 @@ public class NotesPreferenceActivity extends PreferenceActivity { } } + /** + * 移除同步账户 + */ private void removeSyncAccount() { SharedPreferences settings = getSharedPreferences(PREFERENCE_NAME, Context.MODE_PRIVATE); SharedPreferences.Editor editor = settings.edit(); + // 移除账户相关设置 if (settings.contains(PREFERENCE_SYNC_ACCOUNT_NAME)) { editor.remove(PREFERENCE_SYNC_ACCOUNT_NAME); } @@ -329,7 +385,7 @@ public class NotesPreferenceActivity extends PreferenceActivity { } editor.commit(); - // clean up local gtask related info + // 在新线程中清理本地同步信息 new Thread(new Runnable() { public void run() { ContentValues values = new ContentValues(); @@ -340,12 +396,18 @@ public class NotesPreferenceActivity extends PreferenceActivity { }).start(); } + /** + * 静态方法：获取当前同步账户名称 + */ 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) { SharedPreferences settings = context.getSharedPreferences(PREFERENCE_NAME, Context.MODE_PRIVATE); @@ -354,29 +416,38 @@ public class NotesPreferenceActivity extends PreferenceActivity { editor.commit(); } + /** + * 静态方法：获取最后同步时间 + */ 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 { - @Override public void onReceive(Context context, Intent intent) { - refreshUI(); + refreshUI(); // 收到广播后刷新界面 if (intent.getBooleanExtra(GTaskSyncService.GTASK_SERVICE_BROADCAST_IS_SYNCING, false)) { + // 更新同步进度显示 TextView syncStatus = (TextView) findViewById(R.id.prefenerece_sync_status_textview); syncStatus.setText(intent .getStringExtra(GTaskSyncService.GTASK_SERVICE_BROADCAST_PROGRESS_MSG)); } - } } + /** + * 选项菜单项选择处理 + */ public boolean onOptionsItemSelected(MenuItem item) { switch (item.getItemId()) { case android.R.id.home: + // 点击返回按钮，返回到笔记列表 Intent intent = new Intent(this, NotesListActivity.class); intent.addFlags(Intent.FLAG_ACTIVITY_CLEAR_TOP); startActivity(intent); @@ -385,4 +456,4 @@ public class NotesPreferenceActivity extends PreferenceActivity { return false; } } -} +} \ No newline at end of file diff --git a/src/notes/widget/NoteWidgetProvider.java b/src/notes/widget/NoteWidgetProvider.java index ec6f819..fa5c64a 100644 --- a/src/notes/widget/NoteWidgetProvider.java +++ b/src/notes/widget/NoteWidgetProvider.java @@ -15,6 +15,7 @@ */ package net.micode.notes.widget; + import android.app.PendingIntent; import android.appwidget.AppWidgetManager; import android.appwidget.AppWidgetProvider; @@ -32,101 +33,181 @@ 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 static final String [] PROJECTION = new String [] { - NoteColumns.ID, - NoteColumns.BG_COLOR_ID, - NoteColumns.SNIPPET + NoteColumns.ID, // 便签ID + NoteColumns.BG_COLOR_ID, // 背景颜色ID + NoteColumns.SNIPPET // 便签内容摘要 }; - public static final int COLUMN_ID = 0; - public static final int COLUMN_BG_COLOR_ID = 1; - public static final int COLUMN_SNIPPET = 2; + /** + * 投影字段索引常量 + */ + public static final int COLUMN_ID = 0; // ID列索引 + public static final int COLUMN_BG_COLOR_ID = 1; // 背景颜色ID列索引 + public static final int COLUMN_SNIPPET = 2; // 内容摘要列索引 + /** + * 日志标签 + */ private static final String TAG = "NoteWidgetProvider"; @Override public void onDeleted(Context context, int[] appWidgetIds) { + /** + * 处理小部件删除事件 + * 当用户从桌面移除小部件时调用，清理数据库中的小部件关联 + */ + // 创建内容值，用于清除小部件ID关联 ContentValues values = new ContentValues(); values.put(NoteColumns.WIDGET_ID, AppWidgetManager.INVALID_APPWIDGET_ID); + + // 遍历所有被删除的小部件ID for (int i = 0; i < appWidgetIds.length; i++) { + // 更新数据库，将对应的小部件ID设为无效值 context.getContentResolver().update(Notes.CONTENT_NOTE_URI, values, - NoteColumns.WIDGET_ID + "=?", + NoteColumns.WIDGET_ID + "=?", // 条件：小部件ID匹配 new String[] { String.valueOf(appWidgetIds[i])}); } } + /** + * 获取小部件关联的便签信息 + * @param context 上下文对象 + * @param widgetId 小部件ID + * @return 包含便签信息的Cursor对象 + */ private Cursor getNoteWidgetInfo(Context context, int widgetId) { + /** + * 查询数据库获取指定小部件关联的便签信息 + * 条件：小部件ID匹配且不在回收站中 + */ return context.getContentResolver().query(Notes.CONTENT_NOTE_URI, - PROJECTION, - NoteColumns.WIDGET_ID + "=? AND " + NoteColumns.PARENT_ID + "<>?", + PROJECTION, // 查询的列 + NoteColumns.WIDGET_ID + "=? AND " + NoteColumns.PARENT_ID + "<>?", // 查询条件 new String[] { String.valueOf(widgetId), String.valueOf(Notes.ID_TRASH_FOLER) }, - null); + null); // 排序方式（无） } + /** + * 更新小部件显示（公开方法） + * @param context 上下文对象 + * @param appWidgetManager 小部件管理器 + * @param appWidgetIds 要更新的小部件ID数组 + */ protected void update(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds) { + // 调用私有更新方法，默认非隐私模式 update(context, appWidgetManager, appWidgetIds, false); } + /** + * 更新小部件显示（私有方法） + * @param context 上下文对象 + * @param appWidgetManager 小部件管理器 + * @param appWidgetIds 要更新的小部件ID数组 + * @param privacyMode 是否为隐私模式（true:显示保护文本，false:显示便签内容） + */ private void update(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds, - boolean privacyMode) { + boolean privacyMode) { + // 遍历所有需要更新的小部件 for (int i = 0; i < appWidgetIds.length; i++) { + // 检查小部件ID是否有效 if (appWidgetIds[i] != AppWidgetManager.INVALID_APPWIDGET_ID) { + // 初始化默认背景颜色和内容摘要 int bgId = ResourceParser.getDefaultBgId(context); String snippet = ""; + + // 创建点击小部件时启动的Intent（指向便签编辑页面） Intent intent = new Intent(context, NoteEditActivity.class); - intent.setFlags(Intent.FLAG_ACTIVITY_SINGLE_TOP); - intent.putExtra(Notes.INTENT_EXTRA_WIDGET_ID, appWidgetIds[i]); - intent.putExtra(Notes.INTENT_EXTRA_WIDGET_TYPE, getWidgetType()); + intent.setFlags(Intent.FLAG_ACTIVITY_SINGLE_TOP); // 单例模式 + intent.putExtra(Notes.INTENT_EXTRA_WIDGET_ID, appWidgetIds[i]); // 传递小部件ID + intent.putExtra(Notes.INTENT_EXTRA_WIDGET_TYPE, getWidgetType()); // 传递小部件类型 + // 查询数据库获取小部件关联的便签信息 Cursor c = getNoteWidgetInfo(context, appWidgetIds[i]); if (c != null && c.moveToFirst()) { + // 安全检查：确保一个小部件只关联一个便签 if (c.getCount() > 1) { Log.e(TAG, "Multiple message with same widget id:" + appWidgetIds[i]); c.close(); - return; + return; // 发现数据异常，直接返回 } - 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); + // 从数据库读取便签信息 + snippet = c.getString(COLUMN_SNIPPET); // 获取内容摘要 + bgId = c.getInt(COLUMN_BG_COLOR_ID); // 获取背景颜色ID + intent.putExtra(Intent.EXTRA_UID, c.getLong(COLUMN_ID)); // 传递便签ID + 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); // 设置为新建/编辑动作 } + // 关闭Cursor释放资源 if (c != null) { c.close(); } + // 创建RemoteViews对象，用于更新小部件界面 RemoteViews rv = new RemoteViews(context.getPackageName(), getLayoutId()); + // 设置小部件背景图片 rv.setImageViewResource(R.id.widget_bg_image, getBgResourceId(bgId)); - intent.putExtra(Notes.INTENT_EXTRA_BACKGROUND_ID, bgId); + intent.putExtra(Notes.INTENT_EXTRA_BACKGROUND_ID, bgId); // 传递背景颜色ID + /** - * Generate the pending intent to start host for the widget + * 生成启动宿主Activity的PendingIntent + * 用于处理小部件的点击事件 */ PendingIntent pendingIntent = null; if (privacyMode) { + // 隐私模式：显示保护文本，点击进入主列表页面 rv.setTextViewText(R.id.widget_text, context.getString(R.string.widget_under_visit_mode)); pendingIntent = PendingIntent.getActivity(context, appWidgetIds[i], new Intent( 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); } } } + /** + * 根据背景颜色ID获取对应的背景资源ID + * 抽象方法，由具体子类实现不同小部件的背景资源映射 + * @param bgId 背景颜色ID + * @return 背景图片资源ID + */ protected abstract int getBgResourceId(int bgId); + /** + * 获取小部件的布局资源ID + * 抽象方法，由具体子类实现不同小部件的布局 + * @return 布局资源ID + */ protected abstract int getLayoutId(); + /** + * 获取小部件类型标识 + * 抽象方法，由具体子类实现不同类型的小部件标识 + * @return 小部件类型常量 + */ protected abstract int getWidgetType(); -} +} \ No newline at end of file diff --git a/src/notes/widget/NoteWidgetProvider_2x.java b/src/notes/widget/NoteWidgetProvider_2x.java index adcb2f7..5e30e10 100644 --- a/src/notes/widget/NoteWidgetProvider_2x.java +++ b/src/notes/widget/NoteWidgetProvider_2x.java @@ -23,25 +23,65 @@ import net.micode.notes.R; import net.micode.notes.data.Notes; import net.micode.notes.tool.ResourceParser; - +/** + * 2x2尺寸便签小部件提供者 + * 继承自NoteWidgetProvider抽象基类，实现2x2小部件的具体行为 + * 负责管理桌面2x2网格尺寸的便签小部件显示和交互 + */ public class NoteWidgetProvider_2x extends NoteWidgetProvider { + + /** + * 小部件更新回调方法 + * 当小部件需要更新显示内容时调用，委托给父类的通用更新逻辑 + * + * @param context 上下文对象 + * @param appWidgetManager 小部件管理器，用于操作小部件 + * @param appWidgetIds 需要更新的一组小部件ID + */ @Override public void onUpdate(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds) { + // 调用父类的通用更新逻辑，避免重复代码 + // 父类已经实现了数据查询、界面更新等通用功能 super.update(context, appWidgetManager, appWidgetIds); } + /** + * 获取小部件布局资源ID + * 实现抽象方法，返回2x2小部件专用的布局文件 + * + * @return 2x2小部件的布局资源ID + */ @Override protected int getLayoutId() { + // 返回2x2尺寸小部件的布局文件 + // R.layout.widget_2x 定义了2x2小部件的界面结构 return R.layout.widget_2x; } + /** + * 根据背景颜色ID获取2x2小部件的背景资源ID + * 实现抽象方法，提供2x2尺寸专用的背景图片映射 + * + * @param bgId 背景颜色ID（Notes.COLOR_YELLOW, Notes.COLOR_BLUE等） + * @return 对应颜色的2x2小部件背景图片资源ID + */ @Override protected int getBgResourceId(int bgId) { + // 通过资源解析器获取2x2尺寸专用的背景图片 + // 不同的颜色ID对应不同的背景图片资源 return ResourceParser.WidgetBgResources.getWidget2xBgResource(bgId); } + /** + * 获取小部件类型标识 + * 实现抽象方法，返回2x2小部件的类型常量 + * + * @return 2x2小部件的类型标识符 + */ @Override protected int getWidgetType() { + // 返回2x2小部件的类型常量，用于区分不同尺寸的小部件 + // 在数据存储和Intent传递中标识这是2x2尺寸的小部件 return Notes.TYPE_WIDGET_2X; } -} +} \ No newline at end of file diff --git a/src/notes/widget/NoteWidgetProvider_4x.java b/src/notes/widget/NoteWidgetProvider_4x.java index c12a02e..3fabf31 100644 --- a/src/notes/widget/NoteWidgetProvider_4x.java +++ b/src/notes/widget/NoteWidgetProvider_4x.java @@ -23,24 +23,69 @@ import net.micode.notes.R; import net.micode.notes.data.Notes; import net.micode.notes.tool.ResourceParser; - +/** + * 4x4尺寸便签小部件提供者 + * 继承自NoteWidgetProvider抽象基类，实现4x4大尺寸小部件的具体行为 + * 负责管理桌面4x4网格尺寸的便签小部件显示和交互，提供更大的显示区域 + */ public class NoteWidgetProvider_4x extends NoteWidgetProvider { + + /** + * 小部件更新回调方法 + * 当小部件需要更新显示内容时调用，复用父类的通用更新逻辑 + * 4x4小部件使用与2x2相同的更新机制，但显示布局和背景资源不同 + * + * @param context 上下文对象，用于访问应用资源和服务 + * @param appWidgetManager 小部件管理器实例，用于执行小部件更新操作 + * @param appWidgetIds 需要更新的小部件ID数组，支持批量更新多个小部件实例 + */ @Override public void onUpdate(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds) { + // 直接调用父类的通用更新逻辑，避免代码重复 + // 父类已实现数据查询、界面绑定、点击事件等完整的小部件更新流程 super.update(context, appWidgetManager, appWidgetIds); } + /** + * 获取4x4小部件专用布局资源ID + * 实现抽象方法，返回针对4x4网格尺寸优化的布局文件 + * 4x4布局相比2x2具有更大的显示区域，可以展示更多内容 + * + * @return 4x4小部件的布局资源ID，定义在R.layout.widget_4x中 + */ + @Override protected int getLayoutId() { + // 返回4x4尺寸专用的布局文件 + // 该布局针对4x4网格进行了优化，可能包含更大的文本区域或额外的显示元素 return R.layout.widget_4x; } + /** + * 根据背景颜色ID获取4x4小部件的背景资源ID + * 实现抽象方法，提供4x4尺寸专用的背景图片映射 + * 4x4背景图片在尺寸和比例上与2x2不同，适配更大的显示区域 + * + * @param bgId 背景颜色ID（Notes.COLOR_YELLOW, Notes.COLOR_BLUE等颜色常量） + * @return 对应颜色的4x4小部件背景图片资源ID + */ @Override protected int getBgResourceId(int bgId) { + // 通过资源解析器获取4x4尺寸专用的背景图片资源 + // ResourceParser.WidgetBgResources.getWidget4xBgResource()专门处理4x4尺寸的背景映射 return ResourceParser.WidgetBgResources.getWidget4xBgResource(bgId); } + /** + * 获取小部件类型标识符 + * 实现抽象方法，返回4x4小部件的唯一类型常量 + * 该标识符用于在数据库和Intent中区分不同尺寸的小部件 + * + * @return 4x4小部件的类型标识符，值为Notes.TYPE_WIDGET_4X + */ @Override protected int getWidgetType() { + // 返回4x4小部件的类型常量 + // 这个值会存储在数据库中，用于关联便签数据和小部件实例 return Notes.TYPE_WIDGET_4X; } -} +} \ No newline at end of file