();
diff --git a/src/data/Notes.java b/src/data/Notes.java
index f240604..4100147 100644
--- a/src/data/Notes.java
+++ b/src/data/Notes.java
@@ -17,263 +17,562 @@
package net.micode.notes.data;
import android.net.Uri;
+
+/**
+ * 便签应用的核心数据定义类，包含所有常量、URI和数据列定义
+ *
+ * 核心职责：
+ *
+ * - 定义便签和文件夹的类型常量
+ * - 定义系统文件夹的ID常量
+ * - 定义Intent传递的额外数据键
+ * - 定义Widget类型常量
+ * - 定义Content Provider的URI
+ * - 定义数据列接口和内部数据类
+ *
+ *
+ * 设计意图：
+ *
+ * - 集中管理所有数据相关的常量，提高代码的可维护性
+ * - 为Content Provider提供统一的数据定义
+ * - 为应用各组件间的通信提供标准常量
+ * - 支持多种便签类型（文本便签、通话便签）
+ * - 支持便签的分类管理（文件夹、回收站）
+ * - 支持Widget功能
+ *
+ *
+ * 与其他类的关键关联：
+ *
+ * - 被{@link NotesProvider}使用，作为Content Provider的数据源定义
+ * - 被{@link NotesDatabaseHelper}使用，用于数据库表结构定义
+ * - 被UI组件使用，用于Intent传递和数据查询
+ * - 被Widget组件使用，用于Widget类型定义和数据传递
+ *
+ *
+
+ */
public class Notes {
+ /**
+ * Content Provider的Authority，用于标识便签应用的Content Provider
+ */
public static final String AUTHORITY = "micode_notes";
+
+ /**
+ * 日志标签，用于调试和日志记录
+ */
public static final String TAG = "Notes";
+
+ /**
+ * 便签类型常量：普通便签
+ */
public static final int TYPE_NOTE = 0;
+
+ /**
+ * 便签类型常量：文件夹
+ */
public static final int TYPE_FOLDER = 1;
+
+ /**
+ * 便签类型常量：系统类型（保留用于系统内部使用）
+ */
public static final int TYPE_SYSTEM = 2;
/**
- * Following IDs are system folders' identifiers
- * {@link Notes#ID_ROOT_FOLDER } is default folder
- * {@link Notes#ID_TEMPARAY_FOLDER } is for notes belonging no folder
- * {@link Notes#ID_CALL_RECORD_FOLDER} is to store call records
+ * 系统文件夹ID：根文件夹，所有普通便签的默认父文件夹
*/
public static final int ID_ROOT_FOLDER = 0;
+
+ /**
+ * 系统文件夹ID：临时文件夹，用于存放无归属的便签
+ */
public static final int ID_TEMPARAY_FOLDER = -1;
+
+ /**
+ * 系统文件夹ID：通话记录文件夹，用于存放自动生成的通话便签
+ */
public static final int ID_CALL_RECORD_FOLDER = -2;
+
+ /**
+ * 系统文件夹ID：回收站文件夹，用于存放已删除的便签
+ */
public static final int ID_TRASH_FOLER = -3;
+ /**
+ * Intent额外数据键：提醒日期，用于传递便签的提醒时间
+ */
public static final String INTENT_EXTRA_ALERT_DATE = "net.micode.notes.alert_date";
+
+ /**
+ * Intent额外数据键：背景颜色ID，用于传递便签的背景颜色设置
+ */
public static final String INTENT_EXTRA_BACKGROUND_ID = "net.micode.notes.background_color_id";
+
+ /**
+ * Intent额外数据键：Widget ID，用于传递Widget的唯一标识
+ */
public static final String INTENT_EXTRA_WIDGET_ID = "net.micode.notes.widget_id";
+
+ /**
+ * Intent额外数据键：Widget类型，用于传递Widget的类型（2x或4x）
+ */
public static final String INTENT_EXTRA_WIDGET_TYPE = "net.micode.notes.widget_type";
+
+ /**
+ * Intent额外数据键：文件夹ID，用于传递便签所属的文件夹ID
+ */
public static final String INTENT_EXTRA_FOLDER_ID = "net.micode.notes.folder_id";
+
+ /**
+ * Intent额外数据键：通话日期，用于传递通话记录的日期
+ */
public static final String INTENT_EXTRA_CALL_DATE = "net.micode.notes.call_date";
+ /**
+ * Widget类型常量：无效Widget类型
+ */
public static final int TYPE_WIDGET_INVALIDE = -1;
+
+ /**
+ * Widget类型常量：2x尺寸Widget（2x2网格）
+ */
public static final int TYPE_WIDGET_2X = 0;
+
+ /**
+ * Widget类型常量：4x尺寸Widget（4x4网格）
+ */
public static final int TYPE_WIDGET_4X = 1;
+ /**
+ * 数据类型常量类，定义不同类型便签的MIME类型
+ *
+ * 核心职责：
+ *
+ * - 提供统一的数据类型访问入口
+ * - 封装不同类型便签的MIME类型定义
+ *
+ */
public static class DataConstants {
+ /**
+ * 文本便签的MIME类型
+ */
public static final String NOTE = TextNote.CONTENT_ITEM_TYPE;
+
+ /**
+ * 通话便签的MIME类型
+ */
public static final String CALL_NOTE = CallNote.CONTENT_ITEM_TYPE;
}
/**
- * Uri to query all notes and folders
+ * Content Provider URI：用于查询所有便签和文件夹
+ *
+ * 该URI指向Content Provider的note表，返回所有便签和文件夹的列表
*/
public static final Uri CONTENT_NOTE_URI = Uri.parse("content://" + AUTHORITY + "/note");
/**
- * Uri to query data
+ * Content Provider URI：用于查询便签详细数据
+ *
+ * 该URI指向Content Provider的data表，返回便签的具体内容数据
*/
public static final Uri CONTENT_DATA_URI = Uri.parse("content://" + AUTHORITY + "/data");
+ /**
+ * 便签和文件夹的通用列定义接口
+ *
+ * 核心职责：
+ *
+ * - 定义便签和文件夹表的通用字段
+ * - 为Content Provider提供统一的列名定义
+ * - 支持便签和文件夹的基本属性存储
+ *
+ *
+ * 设计意图：
+ *
+ * - 使用接口定义列名，便于在不同组件间共享
+ * - 支持便签和文件夹的统一管理
+ * - 包含基本的元数据字段（创建时间、修改时间、ID等）
+ * - 支持便签的提醒功能
+ * - 支持便签的Widget关联
+ * - 支持便签的背景颜色设置
+ * - 支持便签的同步功能
+ *
+ *
+ * 与其他类的关联：
+ *
+ * - 被{@link NotesProvider}使用，作为查询和操作的列名
+ * - 被{@link NotesDatabaseHelper}使用，用于创建数据库表
+ * - 被UI组件使用，用于构建查询条件和显示数据
+ *
+ */
public interface NoteColumns {
/**
- * The unique ID for a row
- * Type: INTEGER (long)
+ * 行的唯一标识符
+ * 类型: INTEGER (long)
+ * 约束: 主键，自增长
*/
public static final String ID = "_id";
/**
- * The parent's id for note or folder
- * Type: INTEGER (long)
+ * 便签或文件夹的父级ID
+ * 类型: INTEGER (long)
+ * 约束: 指向同一表中的ID字段
+ * 用途: 用于构建便签和文件夹的层级结构
*/
public static final String PARENT_ID = "parent_id";
/**
- * Created data for note or folder
- * Type: INTEGER (long)
+ * 便签或文件夹的创建时间
+ * 类型: INTEGER (long)
+ * 约束: Unix时间戳，毫秒级
+ * 用途: 记录创建时间，用于排序和显示
*/
public static final String CREATED_DATE = "created_date";
/**
- * Latest modified date
- * Type: INTEGER (long)
+ * 最近修改时间
+ * 类型: INTEGER (long)
+ * 约束: Unix时间戳，毫秒级
+ * 用途: 记录最后修改时间，用于排序、同步和显示
*/
public static final String MODIFIED_DATE = "modified_date";
-
/**
- * Alert date
- * Type: INTEGER (long)
+ * 提醒日期
+ * 类型: INTEGER (long)
+ * 约束: Unix时间戳，毫秒级；0表示无提醒
+ * 用途: 用于便签的提醒功能，指定提醒时间
*/
public static final String ALERTED_DATE = "alert_date";
/**
- * Folder's name or text content of note
- * Type: TEXT
+ * 文件夹名称或便签文本内容的摘要
+ * 类型: TEXT
+ * 约束: 最大长度根据数据库配置而定
+ * 用途: 快速显示便签或文件夹的基本信息
*/
public static final String SNIPPET = "snippet";
/**
- * Note's widget id
- * Type: INTEGER (long)
+ * 便签关联的Widget ID
+ * 类型: INTEGER (long)
+ * 约束: -1表示无关联Widget
+ * 用途: 用于关联便签和对应的Widget组件
*/
public static final String WIDGET_ID = "widget_id";
/**
- * Note's widget type
- * Type: INTEGER (long)
+ * 便签关联的Widget类型
+ * 类型: INTEGER (long)
+ * 约束: 取值范围为{@link Notes#TYPE_WIDGET_INVALIDE}、{@link Notes#TYPE_WIDGET_2X}、{@link Notes#TYPE_WIDGET_4X}
+ * 用途: 用于标识关联Widget的尺寸类型
*/
public static final String WIDGET_TYPE = "widget_type";
/**
- * Note's background color's id
- * Type: INTEGER (long)
+ * 便签背景颜色的ID
+ * 类型: INTEGER (long)
+ * 约束: 指向预定义的颜色资源ID
+ * 用途: 用于设置和显示便签的背景颜色
*/
public static final String BG_COLOR_ID = "bg_color_id";
/**
- * For text note, it doesn't has attachment, for multi-media
- * note, it has at least one attachment
- * Type: INTEGER
+ * 是否包含附件
+ * 类型: INTEGER
+ * 约束: 0表示无附件，1表示有附件
+ * 用途: 用于标识便签是否包含多媒体附件
*/
public static final String HAS_ATTACHMENT = "has_attachment";
/**
- * Folder's count of notes
- * Type: INTEGER (long)
+ * 文件夹包含的便签数量
+ * 类型: INTEGER (long)
+ * 约束: 非负数
+ * 用途: 用于快速显示文件夹中的便签数量
*/
public static final String NOTES_COUNT = "notes_count";
/**
- * The file type: folder or note
- * Type: INTEGER
+ * 类型：文件夹或便签
+ * 类型: INTEGER
+ * 约束: 取值范围为{@link Notes#TYPE_NOTE}、{@link Notes#TYPE_FOLDER}、{@link Notes#TYPE_SYSTEM}
+ * 用途: 用于区分便签和文件夹
*/
public static final String TYPE = "type";
/**
- * The last sync id
- * Type: INTEGER (long)
+ * 最后同步ID
+ * 类型: INTEGER (long)
+ * 约束: 用于同步机制，标识同步状态
+ * 用途: 用于便签的云同步功能，跟踪同步进度
*/
public static final String SYNC_ID = "sync_id";
/**
- * Sign to indicate local modified or not
- * Type: INTEGER
+ * 本地修改标记
+ * 类型: INTEGER
+ * 约束: 0表示未修改，1表示已修改
+ * 用途: 用于同步机制，标识本地是否有未同步的修改
*/
public static final String LOCAL_MODIFIED = "local_modified";
/**
- * Original parent id before moving into temporary folder
- * Type : INTEGER
+ * 移动到临时文件夹前的原始父ID
+ * 类型: INTEGER
+ * 约束: 指向原父文件夹的ID
+ * 用途: 用于临时文件夹中的便签，便于恢复到原位置
*/
public static final String ORIGIN_PARENT_ID = "origin_parent_id";
/**
- * The gtask id
- * Type : TEXT
+ * Google Task ID
+ * 类型: TEXT
+ * 约束: 与Google Task服务同步时使用
+ * 用途: 用于便签与Google Task的同步功能
*/
public static final String GTASK_ID = "gtask_id";
/**
- * The version code
- * Type : INTEGER (long)
+ * 版本号
+ * 类型: INTEGER (long)
+ * 约束: 用于乐观锁机制，防止并发修改冲突
+ * 用途: 用于同步和并发控制，确保数据一致性
*/
public static final String VERSION = "version";
}
+ /**
+ * 便签详细数据的列定义接口
+ *
+ * 核心职责：
+ *
+ * - 定义便签详细数据表的通用字段
+ * - 为不同类型的便签数据提供统一的存储结构
+ * - 支持便签内容的扩展存储
+ *
+ *
+ * 设计意图：
+ *
+ * - 使用接口定义列名，便于在不同组件间共享
+ * - 支持多种类型的便签数据存储（文本便签、通话便签等）
+ * - 采用通用字段设计，便于扩展新的便签类型
+ * - 包含基本的元数据字段（创建时间、修改时间、ID等）
+ * - 支持便签内容的灵活存储
+ *
+ *
+ * 与其他类的关联：
+ *
+ * - 被{@link NotesProvider}使用，作为查询和操作的列名
+ * - 被{@link NotesDatabaseHelper}使用，用于创建数据库表
+ * - 被{@link TextNote}和{@link CallNote}内部类继承，用于定义特定类型便签的字段映射
+ *
+ */
public interface DataColumns {
/**
- * The unique ID for a row
- * Type: INTEGER (long)
+ * 行的唯一标识符
+ * 类型: INTEGER (long)
+ * 约束: 主键，自增长
*/
public static final String ID = "_id";
/**
- * The MIME type of the item represented by this row.
- * Type: Text
+ * 该行数据表示的项目的MIME类型
+ * 类型: TEXT
+ * 约束: 唯一标识数据类型，如"text_note"、"call_note"等
+ * 用途: 用于区分不同类型的便签数据
*/
public static final String MIME_TYPE = "mime_type";
/**
- * The reference id to note that this data belongs to
- * Type: INTEGER (long)
+ * 该数据所属的便签ID
+ * 类型: INTEGER (long)
+ * 约束: 外键，指向note表的ID字段
+ * 用途: 建立便签基本信息与详细数据的关联关系
*/
public static final String NOTE_ID = "note_id";
/**
- * Created data for note or folder
- * Type: INTEGER (long)
+ * 数据的创建时间
+ * 类型: INTEGER (long)
+ * 约束: Unix时间戳，毫秒级
+ * 用途: 记录创建时间，用于排序和显示
*/
public static final String CREATED_DATE = "created_date";
/**
- * Latest modified date
- * Type: INTEGER (long)
+ * 数据的最近修改时间
+ * 类型: INTEGER (long)
+ * 约束: Unix时间戳，毫秒级
+ * 用途: 记录最后修改时间，用于排序、同步和显示
*/
public static final String MODIFIED_DATE = "modified_date";
/**
- * Data's content
- * Type: TEXT
+ * 数据的内容
+ * 类型: TEXT
+ * 约束: 可变长度，存储便签的实际内容
+ * 用途: 存储便签的文本内容或其他主要数据
*/
public static final String CONTENT = "content";
-
/**
- * Generic data column, the meaning is {@link #MIMETYPE} specific, used for
- * integer data type
- * Type: INTEGER
+ * 通用数据列1，含义由{@link #MIME_TYPE}决定，用于整数数据类型
+ * 类型: INTEGER
+ * 约束: 含义取决于具体的MIME类型
+ * 用途: 用于存储特定类型便签的额外整数数据
+ * 例如: 文本便签用于存储模式（普通模式/ checklist模式）
*/
public static final String DATA1 = "data1";
/**
- * Generic data column, the meaning is {@link #MIMETYPE} specific, used for
- * integer data type
- * Type: INTEGER
+ * 通用数据列2，含义由{@link #MIME_TYPE}决定，用于整数数据类型
+ * 类型: INTEGER
+ * 约束: 含义取决于具体的MIME类型
+ * 用途: 用于存储特定类型便签的额外整数数据
*/
public static final String DATA2 = "data2";
/**
- * Generic data column, the meaning is {@link #MIMETYPE} specific, used for
- * TEXT data type
- * Type: TEXT
+ * 通用数据列3，含义由{@link #MIME_TYPE}决定，用于文本数据类型
+ * 类型: TEXT
+ * 约束: 含义取决于具体的MIME类型
+ * 用途: 用于存储特定类型便签的额外文本数据
+ * 例如: 通话便签用于存储电话号码
*/
public static final String DATA3 = "data3";
/**
- * Generic data column, the meaning is {@link #MIMETYPE} specific, used for
- * TEXT data type
- * Type: TEXT
+ * 通用数据列4，含义由{@link #MIME_TYPE}决定，用于文本数据类型
+ * 类型: TEXT
+ * 约束: 含义取决于具体的MIME类型
+ * 用途: 用于存储特定类型便签的额外文本数据
*/
public static final String DATA4 = "data4";
/**
- * Generic data column, the meaning is {@link #MIMETYPE} specific, used for
- * TEXT data type
- * Type: TEXT
+ * 通用数据列5，含义由{@link #MIME_TYPE}决定，用于文本数据类型
+ * 类型: TEXT
+ * 约束: 含义取决于具体的MIME类型
+ * 用途: 用于存储特定类型便签的额外文本数据
*/
public static final String DATA5 = "data5";
}
+ /**
+ * 文本便签的数据定义类，实现了{@link DataColumns}接口
+ *
+ * 核心职责：
+ *
+ * - 定义文本便签的特定字段映射
+ * - 定义文本便签的MIME类型
+ * - 定义文本便签的Content Provider URI
+ * - 支持普通文本模式和Checklist模式
+ *
+ *
+ * 设计意图：
+ *
+ * - 扩展{@link DataColumns}接口，为文本便签提供特定的字段映射
+ * - 使用DATA1列存储文本便签的模式（普通模式/Checklist模式）
+ * - 为Content Provider提供文本便签的访问入口
+ * - 支持多种文本便签显示模式
+ *
+ *
+ * 与其他类的关联：
+ *
+ * - 实现{@link DataColumns}接口，继承通用数据列定义
+ * - 被{@link NotesProvider}使用，作为文本便签的数据源定义
+ * - 被UI组件使用，用于查询和显示文本便签
+ *
+ */
public static final class TextNote implements DataColumns {
/**
- * Mode to indicate the text in check list mode or not
- * Type: Integer 1:check list mode 0: normal mode
+ * 文本便签的模式字段，映射到通用数据列DATA1
+ * 类型: INTEGER
+ * 约束: 0表示普通文本模式，1表示Checklist模式
+ * 用途: 用于标识文本便签的显示和编辑模式
*/
public static final String MODE = DATA1;
+ /**
+ * Checklist模式常量，表示文本便签处于Checklist编辑模式
+ */
public static final int MODE_CHECK_LIST = 1;
+ /**
+ * 文本便签集合的MIME类型，用于Content Provider返回多个文本便签时使用
+ */
public static final String CONTENT_TYPE = "vnd.android.cursor.dir/text_note";
+ /**
+ * 单个文本便签的MIME类型，用于Content Provider返回单个文本便签时使用
+ */
public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/text_note";
+ /**
+ * 文本便签的Content Provider URI，用于查询和操作文本便签数据
+ */
public static final Uri CONTENT_URI = Uri.parse("content://" + AUTHORITY + "/text_note");
}
+ /**
+ * 通话便签的数据定义类，实现了{@link DataColumns}接口
+ *
+ * 核心职责：
+ *
+ * - 定义通话便签的特定字段映射
+ * - 定义通话便签的MIME类型
+ * - 定义通话便签的Content Provider URI
+ * - 支持通话记录的自动关联和存储
+ *
+ *
+ * 设计意图：
+ *
+ * - 扩展{@link DataColumns}接口，为通话便签提供特定的字段映射
+ * - 使用DATA1列存储通话日期
+ * - 使用DATA3列存储电话号码
+ * - 为Content Provider提供通话便签的访问入口
+ * - 支持通话记录的自动生成和关联
+ *
+ *
+ * 与其他类的关联：
+ *
+ * - 实现{@link DataColumns}接口，继承通用数据列定义
+ * - 被{@link NotesProvider}使用，作为通话便签的数据源定义
+ * - 被通话记录相关组件使用，用于自动生成通话便签
+ * - 被UI组件使用，用于查询和显示通话便签
+ *
+ */
public static final class CallNote implements DataColumns {
/**
- * Call date for this record
- * Type: INTEGER (long)
+ * 通话日期字段，映射到通用数据列DATA1
+ * 类型: INTEGER (long)
+ * 约束: Unix时间戳，毫秒级
+ * 用途: 存储通话发生的日期和时间
*/
public static final String CALL_DATE = DATA1;
/**
- * Phone number for this record
- * Type: TEXT
+ * 电话号码字段，映射到通用数据列DATA3
+ * 类型: TEXT
+ * 约束: 存储通话记录的电话号码
+ * 用途: 存储通话记录的电话号码，便于用户查看和回拨
*/
public static final String PHONE_NUMBER = DATA3;
+ /**
+ * 通话便签集合的MIME类型，用于Content Provider返回多个通话便签时使用
+ */
public static final String CONTENT_TYPE = "vnd.android.cursor.dir/call_note";
+ /**
+ * 单个通话便签的MIME类型，用于Content Provider返回单个通话便签时使用
+ */
public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/call_note";
+ /**
+ * 通话便签的Content Provider URI，用于查询和操作通话便签数据
+ */
public static final Uri CONTENT_URI = Uri.parse("content://" + AUTHORITY + "/call_note");
}
}
diff --git a/src/data/NotesDatabaseHelper.java b/src/data/NotesDatabaseHelper.java
index ffe5d57..ab3d1ff 100644
--- a/src/data/NotesDatabaseHelper.java
+++ b/src/data/NotesDatabaseHelper.java
@@ -26,190 +26,314 @@ import net.micode.notes.data.Notes.DataColumns;
import net.micode.notes.data.Notes.DataConstants;
import net.micode.notes.data.Notes.NoteColumns;
+/**
+ * 便签应用的数据库核心帮助类，负责数据库的创建、升级和维护
+ *
+ * 核心职责：
+ *
+ * - 负责 "note.db" 数据库的创建 ({@link #onCreate})
+ * - 负责数据库版本升级与数据迁移 ({@link #onUpgrade})
+ * - 定义表名常量（如 {@link TABLE#NOTE}）供外部调用
+ * - 维护 SQL Triggers 以保证数据一致性（如文件夹计数更新）
+ * - 提供单例实例，确保数据库连接的高效管理
+ * - 创建和维护系统文件夹（根文件夹、临时文件夹、通话记录文件夹、回收站）
+ *
+ *
+ * 设计意图：
+ *
+ * - 采用单例模式，避免频繁创建和销毁数据库连接
+ * - 使用SQL Triggers自动维护数据一致性，减少应用层逻辑复杂度
+ * - 提供清晰的版本升级机制，支持平滑的数据迁移
+ * - 将数据库结构定义集中管理，便于维护和扩展
+ * - 支持多种便签类型和关联数据存储
+ *
+ *
+ * 继承关系：
+ *
+ * - 直接继承自 {@link SQLiteOpenHelper}，利用Android系统提供的数据库管理机制
+ *
+ *
+ * 与其他类的关键关联：
+ *
+ * - 被 {@link NotesProvider} 使用，作为Content Provider的底层数据存储
+ * - 使用 {@link Notes} 类中定义的常量和列名，确保数据一致性
+ * - 为整个应用提供统一的数据库访问入口
+ *
+ *
+ * 数据一致性保障：
+ *
+ * - 使用SQL Triggers自动更新文件夹的便签计数
+ * - 实现级联删除，确保数据完整性
+ * - 自动更新便签的摘要内容
+ * - 支持回收站功能，实现安全删除
+ *
+ *
+ */
public class NotesDatabaseHelper extends SQLiteOpenHelper {
+ /**
+ * 数据库名称常量
+ * 数据库文件名：note.db
+ */
private static final String DB_NAME = "note.db";
+ /**
+ * 数据库当前版本号
+ *
+ * 警告：
+ * 任何表结构的修改（如 addColumn）或 Trigger 逻辑的变更，都必须手动 +1。
+ * 这将导致系统自动调用 {@link #onUpgrade} 方法，执行相应的数据迁移操作。
+ *
+ *
+ * 版本历史：
+ *
+ * - 版本1：初始版本
+ * - 版本2：完全重建数据库
+ * - 版本3：添加Google Task ID支持并添加回收站文件夹
+ * - 版本4：添加版本号字段
+ *
+ *
+ */
private static final int DB_VERSION = 4;
+ /**
+ * 表名常量接口，定义数据库中所有表的名称
+ *
+ * 设计意图：
+ *
+ * - 集中管理表名常量，避免硬编码
+ * - 提供统一的表名访问入口，便于维护和扩展
+ * - 被外部类如{@link NotesProvider}使用，确保表名一致性
+ *
+ */
public interface TABLE {
+ /**
+ * 笔记表，存储便签和文件夹的基本信息
+ * 包含字段：ID、PARENT_ID、ALERTED_DATE、BG_COLOR_ID、CREATED_DATE等
+ */
public static final String NOTE = "note";
-
+
+ /**
+ * 数据表，存储便签的详细内容数据
+ * 包含字段：ID、MIME_TYPE、NOTE_ID、CONTENT、DATA1-DATA5等
+ */
public static final String DATA = "data";
}
+ /**
+ * 日志标签，用于调试和日志记录
+ */
private static final String TAG = "NotesDatabaseHelper";
-
+
+ /**
+ * 单例实例，确保整个应用只有一个数据库连接实例
+ *
+ * 设计意图：
+ *
+ * - 避免频繁创建和销毁数据库连接，提高性能
+ * - 确保数据库操作的线程安全
+ * - 通过{@link #getInstance(Context)}方法获取实例
+ *
+ */
private static NotesDatabaseHelper mInstance;
+ /**
+ * 创建笔记表的SQL语句
+ * 包含笔记的基本信息字段：ID、父文件夹ID、提醒日期、背景颜色、创建日期等
+ */
private static final String CREATE_NOTE_TABLE_SQL =
- "CREATE TABLE " + TABLE.NOTE + "(" +
- NoteColumns.ID + " INTEGER PRIMARY KEY," +
- NoteColumns.PARENT_ID + " INTEGER NOT NULL DEFAULT 0," +
- NoteColumns.ALERTED_DATE + " INTEGER NOT NULL DEFAULT 0," +
- NoteColumns.BG_COLOR_ID + " INTEGER NOT NULL DEFAULT 0," +
- NoteColumns.CREATED_DATE + " INTEGER NOT NULL DEFAULT (strftime('%s','now') * 1000)," +
- NoteColumns.HAS_ATTACHMENT + " INTEGER NOT NULL DEFAULT 0," +
- NoteColumns.MODIFIED_DATE + " INTEGER NOT NULL DEFAULT (strftime('%s','now') * 1000)," +
- NoteColumns.NOTES_COUNT + " INTEGER NOT NULL DEFAULT 0," +
- NoteColumns.SNIPPET + " TEXT NOT NULL DEFAULT ''," +
- NoteColumns.TYPE + " INTEGER NOT NULL DEFAULT 0," +
- NoteColumns.WIDGET_ID + " INTEGER NOT NULL DEFAULT 0," +
- NoteColumns.WIDGET_TYPE + " INTEGER NOT NULL DEFAULT -1," +
- NoteColumns.SYNC_ID + " INTEGER NOT NULL DEFAULT 0," +
- NoteColumns.LOCAL_MODIFIED + " INTEGER NOT NULL DEFAULT 0," +
- NoteColumns.ORIGIN_PARENT_ID + " INTEGER NOT NULL DEFAULT 0," +
- NoteColumns.GTASK_ID + " TEXT NOT NULL DEFAULT ''," +
- NoteColumns.VERSION + " INTEGER NOT NULL DEFAULT 0" +
- ")";
+ "CREATE TABLE " + TABLE.NOTE + "(" +
+ NoteColumns.ID + " INTEGER PRIMARY KEY," + // 主键ID
+ NoteColumns.PARENT_ID + " INTEGER NOT NULL DEFAULT 0," + // 父文件夹ID，默认为0
+ NoteColumns.ALERTED_DATE + " INTEGER NOT NULL DEFAULT 0," + // 提醒日期时间戳
+ NoteColumns.BG_COLOR_ID + " INTEGER NOT NULL DEFAULT 0," + // 背景颜色ID
+ NoteColumns.CREATED_DATE + " INTEGER NOT NULL DEFAULT (strftime('%s','now') * 1000)," + // 创建日期，默认为当前时间
+ NoteColumns.HAS_ATTACHMENT + " INTEGER NOT NULL DEFAULT 0," + // 是否有附件
+ NoteColumns.MODIFIED_DATE + " INTEGER NOT NULL DEFAULT (strftime('%s','now') * 1000)," + // 修改日期，默认为当前时间
+ NoteColumns.NOTES_COUNT + " INTEGER NOT NULL DEFAULT 0," + // 笔记数量（用于文件夹）
+ NoteColumns.SNIPPET + " TEXT NOT NULL DEFAULT ''," + // 内容摘要
+ NoteColumns.TYPE + " INTEGER NOT NULL DEFAULT 0," + // 类型（笔记/文件夹/系统文件夹等）
+ NoteColumns.WIDGET_ID + " INTEGER NOT NULL DEFAULT 0," + // 关联的小部件ID
+ NoteColumns.WIDGET_TYPE + " INTEGER NOT NULL DEFAULT -1," + // 小部件类型
+ NoteColumns.SYNC_ID + " INTEGER NOT NULL DEFAULT 0," + // 同步ID
+ NoteColumns.LOCAL_MODIFIED + " INTEGER NOT NULL DEFAULT 0," + // 本地修改标记
+ NoteColumns.ORIGIN_PARENT_ID + " INTEGER NOT NULL DEFAULT 0," + // 原始父文件夹ID
+ NoteColumns.GTASK_ID + " TEXT NOT NULL DEFAULT ''," + // Google Task ID
+ NoteColumns.VERSION + " INTEGER NOT NULL DEFAULT 0" + // 版本号
+ ")";
+ /**
+ * 创建数据表的SQL语句
+ * 存储笔记的具体内容数据，支持多种MIME类型（文本、图片等）
+ */
private static final String CREATE_DATA_TABLE_SQL =
- "CREATE TABLE " + TABLE.DATA + "(" +
- DataColumns.ID + " INTEGER PRIMARY KEY," +
- DataColumns.MIME_TYPE + " TEXT NOT NULL," +
- DataColumns.NOTE_ID + " INTEGER NOT NULL DEFAULT 0," +
- NoteColumns.CREATED_DATE + " INTEGER NOT NULL DEFAULT (strftime('%s','now') * 1000)," +
- NoteColumns.MODIFIED_DATE + " INTEGER NOT NULL DEFAULT (strftime('%s','now') * 1000)," +
- DataColumns.CONTENT + " TEXT NOT NULL DEFAULT ''," +
- DataColumns.DATA1 + " INTEGER," +
- DataColumns.DATA2 + " INTEGER," +
- DataColumns.DATA3 + " TEXT NOT NULL DEFAULT ''," +
- DataColumns.DATA4 + " TEXT NOT NULL DEFAULT ''," +
- DataColumns.DATA5 + " TEXT NOT NULL DEFAULT ''" +
- ")";
+ "CREATE TABLE " + TABLE.DATA + "(" +
+ DataColumns.ID + " INTEGER PRIMARY KEY," + // 主键ID
+ DataColumns.MIME_TYPE + " TEXT NOT NULL," + // MIME类型，标识数据类型
+ DataColumns.NOTE_ID + " INTEGER NOT NULL DEFAULT 0," + // 关联的笔记ID
+ NoteColumns.CREATED_DATE + " INTEGER NOT NULL DEFAULT (strftime('%s','now') * 1000)," + // 创建日期
+ NoteColumns.MODIFIED_DATE + " INTEGER NOT NULL DEFAULT (strftime('%s','now') * 1000)," + // 修改日期
+ DataColumns.CONTENT + " TEXT NOT NULL DEFAULT ''," + // 内容
+ DataColumns.DATA1 + " INTEGER," + // 扩展字段1（整数）
+ DataColumns.DATA2 + " INTEGER," + // 扩展字段2（整数）
+ DataColumns.DATA3 + " TEXT NOT NULL DEFAULT ''," + // 扩展字段3（文本）
+ DataColumns.DATA4 + " TEXT NOT NULL DEFAULT ''," + // 扩展字段4（文本）
+ DataColumns.DATA5 + " TEXT NOT NULL DEFAULT ''" + // 扩展字段5（文本）
+ ")";
+ /**
+ * 在数据表的note_id字段上创建索引，提高查询性能
+ */
private static final String CREATE_DATA_NOTE_ID_INDEX_SQL =
- "CREATE INDEX IF NOT EXISTS note_id_index ON " +
- TABLE.DATA + "(" + DataColumns.NOTE_ID + ");";
+ "CREATE INDEX IF NOT EXISTS note_id_index ON " +
+ TABLE.DATA + "(" + DataColumns.NOTE_ID + ");";
/**
- * Increase folder's note count when move note to the folder
+ * SQL 触发器：移动笔记时自动增加目标文件夹计数
+ *
+ * 逻辑解析：
+ * 1. 监听 {@link TABLE#NOTE} 表的 {@link NoteColumns#PARENT_ID} 字段。
+ * 2. 捕捉更新后的新文件夹 ID (new.parent_id)。
+ * 3. 将该目标文件夹的 'note_count' 字段 +1。
+ *
*/
private static final String NOTE_INCREASE_FOLDER_COUNT_ON_UPDATE_TRIGGER =
- "CREATE TRIGGER increase_folder_count_on_update "+
- " AFTER UPDATE OF " + NoteColumns.PARENT_ID + " ON " + TABLE.NOTE +
- " BEGIN " +
- " UPDATE " + TABLE.NOTE +
- " SET " + NoteColumns.NOTES_COUNT + "=" + NoteColumns.NOTES_COUNT + " + 1" +
- " WHERE " + NoteColumns.ID + "=new." + NoteColumns.PARENT_ID + ";" +
- " END";
+ "CREATE TRIGGER increase_folder_count_on_update "+
+ " AFTER UPDATE OF " + NoteColumns.PARENT_ID + " ON " + TABLE.NOTE +
+ " BEGIN " +
+ " UPDATE " + TABLE.NOTE +
+ " SET " + NoteColumns.NOTES_COUNT + "=" + NoteColumns.NOTES_COUNT + " + 1" +
+ " WHERE " + NoteColumns.ID + "=new." + NoteColumns.PARENT_ID + ";" +
+ " END";
/**
- * Decrease folder's note count when move note from folder
+ * SQL 触发器：当笔记从文件夹移出时，减少原文件夹的笔记计数
+ * 注意：只减少计数大于0的文件夹
*/
private static final String NOTE_DECREASE_FOLDER_COUNT_ON_UPDATE_TRIGGER =
- "CREATE TRIGGER decrease_folder_count_on_update " +
- " AFTER UPDATE OF " + NoteColumns.PARENT_ID + " ON " + TABLE.NOTE +
- " BEGIN " +
- " UPDATE " + TABLE.NOTE +
- " SET " + NoteColumns.NOTES_COUNT + "=" + NoteColumns.NOTES_COUNT + "-1" +
- " WHERE " + NoteColumns.ID + "=old." + NoteColumns.PARENT_ID +
- " AND " + NoteColumns.NOTES_COUNT + ">0" + ";" +
- " END";
+ "CREATE TRIGGER decrease_folder_count_on_update " +
+ " AFTER UPDATE OF " + NoteColumns.PARENT_ID + " ON " + TABLE.NOTE +
+ " BEGIN " +
+ " UPDATE " + TABLE.NOTE +
+ " SET " + NoteColumns.NOTES_COUNT + "=" + NoteColumns.NOTES_COUNT + "-1" +
+ " WHERE " + NoteColumns.ID + "=old." + NoteColumns.PARENT_ID +
+ " AND " + NoteColumns.NOTES_COUNT + ">0" + ";" +
+ " END";
/**
- * Increase folder's note count when insert new note to the folder
+ * SQL 触发器：插入新笔记时增加父文件夹的笔记计数
*/
private static final String NOTE_INCREASE_FOLDER_COUNT_ON_INSERT_TRIGGER =
- "CREATE TRIGGER increase_folder_count_on_insert " +
- " AFTER INSERT ON " + TABLE.NOTE +
- " BEGIN " +
- " UPDATE " + TABLE.NOTE +
- " SET " + NoteColumns.NOTES_COUNT + "=" + NoteColumns.NOTES_COUNT + " + 1" +
- " WHERE " + NoteColumns.ID + "=new." + NoteColumns.PARENT_ID + ";" +
- " END";
+ "CREATE TRIGGER increase_folder_count_on_insert " +
+ " AFTER INSERT ON " + TABLE.NOTE +
+ " BEGIN " +
+ " UPDATE " + TABLE.NOTE +
+ " SET " + NoteColumns.NOTES_COUNT + "=" + NoteColumns.NOTES_COUNT + " + 1" +
+ " WHERE " + NoteColumns.ID + "=new." + NoteColumns.PARENT_ID + ";" +
+ " END";
/**
- * Decrease folder's note count when delete note from the folder
+ * SQL 触发器：删除笔记时减少父文件夹的笔记计数
+ * 注意：只减少计数大于0的文件夹
*/
private static final String NOTE_DECREASE_FOLDER_COUNT_ON_DELETE_TRIGGER =
- "CREATE TRIGGER decrease_folder_count_on_delete " +
- " AFTER DELETE ON " + TABLE.NOTE +
- " BEGIN " +
- " UPDATE " + TABLE.NOTE +
- " SET " + NoteColumns.NOTES_COUNT + "=" + NoteColumns.NOTES_COUNT + "-1" +
- " WHERE " + NoteColumns.ID + "=old." + NoteColumns.PARENT_ID +
- " AND " + NoteColumns.NOTES_COUNT + ">0;" +
- " END";
+ "CREATE TRIGGER decrease_folder_count_on_delete " +
+ " AFTER DELETE ON " + TABLE.NOTE +
+ " BEGIN " +
+ " UPDATE " + TABLE.NOTE +
+ " SET " + NoteColumns.NOTES_COUNT + "=" + NoteColumns.NOTES_COUNT + "-1" +
+ " WHERE " + NoteColumns.ID + "=old." + NoteColumns.PARENT_ID +
+ " AND " + NoteColumns.NOTES_COUNT + ">0;" +
+ " END";
/**
- * Update note's content when insert data with type {@link DataConstants#NOTE}
+ * SQL 触发器：当插入类型为NOTE的数据时，更新对应笔记的摘要内容
+ * 仅当MIME_TYPE为DataConstants.NOTE时触发
*/
private static final String DATA_UPDATE_NOTE_CONTENT_ON_INSERT_TRIGGER =
- "CREATE TRIGGER update_note_content_on_insert " +
- " AFTER INSERT ON " + TABLE.DATA +
- " WHEN new." + DataColumns.MIME_TYPE + "='" + DataConstants.NOTE + "'" +
- " BEGIN" +
- " UPDATE " + TABLE.NOTE +
- " SET " + NoteColumns.SNIPPET + "=new." + DataColumns.CONTENT +
- " WHERE " + NoteColumns.ID + "=new." + DataColumns.NOTE_ID + ";" +
- " END";
+ "CREATE TRIGGER update_note_content_on_insert " +
+ " AFTER INSERT ON " + TABLE.DATA +
+ " WHEN new." + DataColumns.MIME_TYPE + "='" + DataConstants.NOTE + "'" +
+ " BEGIN" +
+ " UPDATE " + TABLE.NOTE +
+ " SET " + NoteColumns.SNIPPET + "=new." + DataColumns.CONTENT +
+ " WHERE " + NoteColumns.ID + "=new." + DataColumns.NOTE_ID + ";" +
+ " END";
/**
- * Update note's content when data with {@link DataConstants#NOTE} type has changed
+ * SQL 触发器：当更新类型为NOTE的数据时，更新对应笔记的摘要内容
*/
private static final String DATA_UPDATE_NOTE_CONTENT_ON_UPDATE_TRIGGER =
- "CREATE TRIGGER update_note_content_on_update " +
- " AFTER UPDATE ON " + TABLE.DATA +
- " WHEN old." + DataColumns.MIME_TYPE + "='" + DataConstants.NOTE + "'" +
- " BEGIN" +
- " UPDATE " + TABLE.NOTE +
- " SET " + NoteColumns.SNIPPET + "=new." + DataColumns.CONTENT +
- " WHERE " + NoteColumns.ID + "=new." + DataColumns.NOTE_ID + ";" +
- " END";
+ "CREATE TRIGGER update_note_content_on_update " +
+ " AFTER UPDATE ON " + TABLE.DATA +
+ " WHEN old." + DataColumns.MIME_TYPE + "='" + DataConstants.NOTE + "'" +
+ " BEGIN" +
+ " UPDATE " + TABLE.NOTE +
+ " SET " + NoteColumns.SNIPPET + "=new." + DataColumns.CONTENT +
+ " WHERE " + NoteColumns.ID + "=new." + DataColumns.NOTE_ID + ";" +
+ " END";
/**
- * Update note's content when data with {@link DataConstants#NOTE} type has deleted
+ * SQL 触发器：当删除类型为NOTE的数据时，清空对应笔记的摘要内容
*/
private static final String DATA_UPDATE_NOTE_CONTENT_ON_DELETE_TRIGGER =
- "CREATE TRIGGER update_note_content_on_delete " +
- " AFTER delete ON " + TABLE.DATA +
- " WHEN old." + DataColumns.MIME_TYPE + "='" + DataConstants.NOTE + "'" +
- " BEGIN" +
- " UPDATE " + TABLE.NOTE +
- " SET " + NoteColumns.SNIPPET + "=''" +
- " WHERE " + NoteColumns.ID + "=old." + DataColumns.NOTE_ID + ";" +
- " END";
+ "CREATE TRIGGER update_note_content_on_delete " +
+ " AFTER delete ON " + TABLE.DATA +
+ " WHEN old." + DataColumns.MIME_TYPE + "='" + DataConstants.NOTE + "'" +
+ " BEGIN" +
+ " UPDATE " + TABLE.NOTE +
+ " SET " + NoteColumns.SNIPPET + "=''" +
+ " WHERE " + NoteColumns.ID + "=old." + DataColumns.NOTE_ID + ";" +
+ " END";
/**
- * Delete datas belong to note which has been deleted
+ * SQL 触发器：删除笔记时，级联删除其关联的所有数据
*/
private static final String NOTE_DELETE_DATA_ON_DELETE_TRIGGER =
- "CREATE TRIGGER delete_data_on_delete " +
- " AFTER DELETE ON " + TABLE.NOTE +
- " BEGIN" +
- " DELETE FROM " + TABLE.DATA +
- " WHERE " + DataColumns.NOTE_ID + "=old." + NoteColumns.ID + ";" +
- " END";
+ "CREATE TRIGGER delete_data_on_delete " +
+ " AFTER DELETE ON " + TABLE.NOTE +
+ " BEGIN" +
+ " DELETE FROM " + TABLE.DATA +
+ " WHERE " + DataColumns.NOTE_ID + "=old." + NoteColumns.ID + ";" +
+ " END";
/**
- * Delete notes belong to folder which has been deleted
+ * SQL 触发器：删除文件夹时，级联删除其下的所有笔记
+ * 注意：这会触发delete_data_on_delete触发器，从而删除所有关联数据
*/
private static final String FOLDER_DELETE_NOTES_ON_DELETE_TRIGGER =
- "CREATE TRIGGER folder_delete_notes_on_delete " +
- " AFTER DELETE ON " + TABLE.NOTE +
- " BEGIN" +
- " DELETE FROM " + TABLE.NOTE +
- " WHERE " + NoteColumns.PARENT_ID + "=old." + NoteColumns.ID + ";" +
- " END";
+ "CREATE TRIGGER folder_delete_notes_on_delete " +
+ " AFTER DELETE ON " + TABLE.NOTE +
+ " BEGIN" +
+ " DELETE FROM " + TABLE.NOTE +
+ " WHERE " + NoteColumns.PARENT_ID + "=old." + NoteColumns.ID + ";" +
+ " END";
/**
- * Move notes belong to folder which has been moved to trash folder
+ * SQL 触发器：当文件夹被移动到回收站时，将其下的所有笔记也移动到回收站
*/
private static final String FOLDER_MOVE_NOTES_ON_TRASH_TRIGGER =
- "CREATE TRIGGER folder_move_notes_on_trash " +
- " AFTER UPDATE ON " + TABLE.NOTE +
- " WHEN new." + NoteColumns.PARENT_ID + "=" + Notes.ID_TRASH_FOLER +
- " BEGIN" +
- " UPDATE " + TABLE.NOTE +
- " SET " + NoteColumns.PARENT_ID + "=" + Notes.ID_TRASH_FOLER +
- " WHERE " + NoteColumns.PARENT_ID + "=old." + NoteColumns.ID + ";" +
- " END";
+ "CREATE TRIGGER folder_move_notes_on_trash " +
+ " AFTER UPDATE ON " + TABLE.NOTE +
+ " WHEN new." + NoteColumns.PARENT_ID + "=" + Notes.ID_TRASH_FOLER +
+ " BEGIN" +
+ " UPDATE " + TABLE.NOTE +
+ " SET " + NoteColumns.PARENT_ID + "=" + Notes.ID_TRASH_FOLER +
+ " WHERE " + NoteColumns.PARENT_ID + "=old." + NoteColumns.ID + ";" +
+ " END";
+ /**
+ * 构造方法
+ * @param context Android上下文
+ */
public NotesDatabaseHelper(Context context) {
super(context, DB_NAME, null, DB_VERSION);
}
+ /**
+ * 创建笔记表及其相关触发器
+ * @param db SQLite数据库对象
+ */
public void createNoteTable(SQLiteDatabase db) {
db.execSQL(CREATE_NOTE_TABLE_SQL);
reCreateNoteTableTriggers(db);
@@ -217,7 +341,13 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
Log.d(TAG, "note table has been created");
}
+ /**
+ * 重建笔记表的所有触发器
+ * 先删除旧触发器（如果存在），然后创建新触发器
+ * @param db SQLite数据库对象
+ */
private void reCreateNoteTableTriggers(SQLiteDatabase db) {
+ // 删除所有旧触发器
db.execSQL("DROP TRIGGER IF EXISTS increase_folder_count_on_update");
db.execSQL("DROP TRIGGER IF EXISTS decrease_folder_count_on_update");
db.execSQL("DROP TRIGGER IF EXISTS decrease_folder_count_on_delete");
@@ -226,6 +356,7 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
db.execSQL("DROP TRIGGER IF EXISTS folder_delete_notes_on_delete");
db.execSQL("DROP TRIGGER IF EXISTS folder_move_notes_on_trash");
+ // 创建新触发器
db.execSQL(NOTE_INCREASE_FOLDER_COUNT_ON_UPDATE_TRIGGER);
db.execSQL(NOTE_DECREASE_FOLDER_COUNT_ON_UPDATE_TRIGGER);
db.execSQL(NOTE_DECREASE_FOLDER_COUNT_ON_DELETE_TRIGGER);
@@ -235,18 +366,23 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
db.execSQL(FOLDER_MOVE_NOTES_ON_TRASH_TRIGGER);
}
+ /**
+ * 创建系统文件夹
+ * 包括：通话记录文件夹、根文件夹、临时文件夹、回收站
+ * @param db SQLite数据库对象
+ */
private void createSystemFolder(SQLiteDatabase db) {
ContentValues values = new ContentValues();
/**
- * call record foler for call notes
+ * 通话记录文件夹
*/
values.put(NoteColumns.ID, Notes.ID_CALL_RECORD_FOLDER);
values.put(NoteColumns.TYPE, Notes.TYPE_SYSTEM);
db.insert(TABLE.NOTE, null, values);
/**
- * root folder which is default folder
+ * 根文件夹（默认文件夹）
*/
values.clear();
values.put(NoteColumns.ID, Notes.ID_ROOT_FOLDER);
@@ -254,7 +390,7 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
db.insert(TABLE.NOTE, null, values);
/**
- * temporary folder which is used for moving note
+ * 临时文件夹（用于笔记移动操作）
*/
values.clear();
values.put(NoteColumns.ID, Notes.ID_TEMPARAY_FOLDER);
@@ -262,7 +398,7 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
db.insert(TABLE.NOTE, null, values);
/**
- * create trash folder
+ * 回收站文件夹
*/
values.clear();
values.put(NoteColumns.ID, Notes.ID_TRASH_FOLER);
@@ -270,13 +406,22 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
db.insert(TABLE.NOTE, null, values);
}
+ /**
+ * 创建数据表及其相关触发器
+ * @param db SQLite数据库对象
+ */
public void createDataTable(SQLiteDatabase db) {
db.execSQL(CREATE_DATA_TABLE_SQL);
reCreateDataTableTriggers(db);
- db.execSQL(CREATE_DATA_NOTE_ID_INDEX_SQL);
+ db.execSQL(CREATE_DATA_NOTE_ID_INDEX_SQL); // 创建索引提高查询性能
Log.d(TAG, "data table has been created");
}
+ /**
+ * 重建数据表的所有触发器
+ * 先删除旧触发器（如果存在），然后创建新触发器
+ * @param db SQLite数据库对象
+ */
private void reCreateDataTableTriggers(SQLiteDatabase db) {
db.execSQL("DROP TRIGGER IF EXISTS update_note_content_on_insert");
db.execSQL("DROP TRIGGER IF EXISTS update_note_content_on_update");
@@ -287,6 +432,11 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
db.execSQL(DATA_UPDATE_NOTE_CONTENT_ON_DELETE_TRIGGER);
}
+ /**
+ * 获取单例实例（线程安全）
+ * @param context Android上下文
+ * @return NotesDatabaseHelper实例
+ */
static synchronized NotesDatabaseHelper getInstance(Context context) {
if (mInstance == null) {
mInstance = new NotesDatabaseHelper(context);
@@ -294,69 +444,103 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
return mInstance;
}
+ /**
+ * 数据库首次创建时调用
+ * 创建所有表和触发器
+ * @param db SQLite数据库对象
+ */
@Override
public void onCreate(SQLiteDatabase db) {
createNoteTable(db);
createDataTable(db);
}
+ /**
+ * 数据库版本升级时调用
+ * 处理不同版本间的数据迁移和结构变更
+ * @param db SQLite数据库对象
+ * @param oldVersion 旧版本号
+ * @param newVersion 新版本号
+ */
@Override
public void onUpgrade(SQLiteDatabase db, int oldVersion, int newVersion) {
- boolean reCreateTriggers = false;
- boolean skipV2 = false;
+ boolean reCreateTriggers = false; // 是否需要重建触发器
+ boolean skipV2 = false; // 是否跳过V2升级
+ // 从版本1升级到版本2
if (oldVersion == 1) {
upgradeToV2(db);
- skipV2 = true; // this upgrade including the upgrade from v2 to v3
+ skipV2 = true; // V1到V2的升级包含了V2到V3的内容
oldVersion++;
}
+ // 从版本2升级到版本3（如果未跳过）
if (oldVersion == 2 && !skipV2) {
upgradeToV3(db);
- reCreateTriggers = true;
+ reCreateTriggers = true; // V3升级需要重建触发器
oldVersion++;
}
+ // 从版本3升级到版本4
if (oldVersion == 3) {
upgradeToV4(db);
oldVersion++;
}
+ // 如果需要，重建所有触发器
if (reCreateTriggers) {
reCreateNoteTableTriggers(db);
reCreateDataTableTriggers(db);
}
+ // 版本号检查，确保升级完成
if (oldVersion != newVersion) {
throw new IllegalStateException("Upgrade notes database to version " + newVersion
+ "fails");
}
}
+ /**
+ * 升级到版本2：完全重建数据库
+ * @param db SQLite数据库对象
+ */
private void upgradeToV2(SQLiteDatabase db) {
+ // 删除旧表
db.execSQL("DROP TABLE IF EXISTS " + TABLE.NOTE);
db.execSQL("DROP TABLE IF EXISTS " + TABLE.DATA);
+ // 创建新表
createNoteTable(db);
createDataTable(db);
}
+ /**
+ * 升级到版本3：添加Google Task ID支持并添加回收站文件夹
+ * @param db SQLite数据库对象
+ */
private void upgradeToV3(SQLiteDatabase db) {
- // drop unused triggers
+ // 删除不再使用的触发器
db.execSQL("DROP TRIGGER IF EXISTS update_note_modified_date_on_insert");
db.execSQL("DROP TRIGGER IF EXISTS update_note_modified_date_on_delete");
db.execSQL("DROP TRIGGER IF EXISTS update_note_modified_date_on_update");
- // add a column for gtask id
+
+ // 添加Google Task ID字段
db.execSQL("ALTER TABLE " + TABLE.NOTE + " ADD COLUMN " + NoteColumns.GTASK_ID
+ " TEXT NOT NULL DEFAULT ''");
- // add a trash system folder
+
+ // 添加回收站系统文件夹
ContentValues values = new ContentValues();
values.put(NoteColumns.ID, Notes.ID_TRASH_FOLER);
values.put(NoteColumns.TYPE, Notes.TYPE_SYSTEM);
db.insert(TABLE.NOTE, null, values);
}
+ /**
+ * 升级到版本4：添加版本号字段
+ * @param db SQLite数据库对象
+ */
private void upgradeToV4(SQLiteDatabase db) {
+ // 添加版本号字段
db.execSQL("ALTER TABLE " + TABLE.NOTE + " ADD COLUMN " + NoteColumns.VERSION
+ " INTEGER NOT NULL DEFAULT 0");
}
-}
+}
\ No newline at end of file
diff --git a/src/data/NotesProvider.java b/src/data/NotesProvider.java
index edb0a60..e018e95 100644
--- a/src/data/NotesProvider.java
+++ b/src/data/NotesProvider.java
@@ -35,21 +35,120 @@ import net.micode.notes.data.Notes.NoteColumns;
import net.micode.notes.data.NotesDatabaseHelper.TABLE;
+/**
+ * 便签应用的Content Provider，负责处理便签数据的CRUD操作和搜索功能
+ *
+ * 核心职责：
+ *
+ * - 提供便签数据的Content Provider访问接口
+ * - 处理便签和便签详细数据的查询、插入、更新、删除操作
+ * - 支持便签搜索和搜索建议功能
+ * - 管理便签数据的版本控制
+ * - 在数据变更时通知相关组件
+ *
+ *
+ * 设计意图：
+ *
+ * - 遵循Android Content Provider设计规范，提供统一的数据访问接口
+ * - 使用UriMatcher处理不同类型的URI请求
+ * - 实现数据的封装和隔离，保护数据安全
+ * - 支持跨应用数据访问（如果需要）
+ * - 集成Android搜索框架，支持全局搜索
+ *
+ *
+ * 继承关系：
+ *
+ * - 直接继承自{@link android.content.ContentProvider}，实现标准的Content Provider接口
+ *
+ *
+ * 与其他类的关键关联：
+ *
+ * - 依赖{@link NotesDatabaseHelper}获取数据库实例，进行底层数据操作
+ * - 使用{@link Notes}类中定义的常量和URI，作为数据访问的标准
+ * - 实现{@link SearchManager}接口，支持Android全局搜索功能
+ * - 被应用的UI组件和Widget组件使用，作为数据访问的主要入口
+ *
+ *
+ * URI匹配规则：
+ *
+ * - content://micode_notes/note - 所有便签和文件夹
+ * - content://micode_notes/note/# - 单个便签或文件夹
+ * - content://micode_notes/data - 所有便签详细数据
+ * - content://micode_notes/data/# - 单个便签详细数据
+ * - content://micode_notes/search - 搜索便签
+ * - content://micode_notes/search_suggest_query - 搜索建议
+ *
+ *
+
+ */
public class NotesProvider extends ContentProvider {
+ /**
+ * UriMatcher实例，用于匹配不同类型的URI请求
+ *
+ * 用途：根据URI路径和格式，将请求分发到不同的处理逻辑
+ *
+ * 初始化：在静态代码块中初始化，添加所有支持的URI模式
+ */
private static final UriMatcher mMatcher;
+ /**
+ * 数据库辅助类实例，用于获取SQLiteDatabase对象
+ *
+ * 用途：提供底层数据库操作支持，包括创建、打开和升级数据库
+ *
+ * 初始化：在onCreate方法中通过单例模式获取实例
+ */
private NotesDatabaseHelper mHelper;
+ /**
+ * 日志标签，用于调试和日志记录
+ */
private static final String TAG = "NotesProvider";
+ /**
+ * URI类型常量：表示所有便签和文件夹的集合
+ */
private static final int URI_NOTE = 1;
+
+ /**
+ * URI类型常量：表示单个便签或文件夹
+ */
private static final int URI_NOTE_ITEM = 2;
+
+ /**
+ * URI类型常量：表示所有便签详细数据的集合
+ */
private static final int URI_DATA = 3;
+
+ /**
+ * URI类型常量：表示单个便签详细数据
+ */
private static final int URI_DATA_ITEM = 4;
+ /**
+ * URI类型常量：表示便签搜索请求
+ */
private static final int URI_SEARCH = 5;
+
+ /**
+ * URI类型常量：表示搜索建议请求
+ */
private static final int URI_SEARCH_SUGGEST = 6;
+ /**
+ * 静态代码块，初始化UriMatcher实例，添加所有支持的URI模式
+ *
+ * 注册的URI模式包括：
+ *
+ * - note - 所有便签和文件夹
+ * - note/# - 单个便签或文件夹
+ * - data - 所有便签详细数据
+ * - data/# - 单个便签详细数据
+ * - search - 便签搜索
+ * - search_suggest_query - 搜索建议
+ * - search_suggest_query/* - 带查询参数的搜索建议
+ *
+ */
static {
mMatcher = new UriMatcher(UriMatcher.NO_MATCH);
mMatcher.addURI(Notes.AUTHORITY, "note", URI_NOTE);
@@ -62,8 +161,24 @@ public class NotesProvider extends ContentProvider {
}
/**
- * x'0A' represents the '\n' character in sqlite. For title and content in the search result,
- * we will trim '\n' and white space in order to show more information.
+ * 便签搜索的投影列定义，用于构建搜索结果
+ *
+ * 包含以下字段：
+ *
+ * - 便签ID
+ * - 搜索建议的额外数据（便签ID）
+ * - 搜索建议的文本1（便签内容，去除换行符和空格）
+ * - 搜索建议的文本2（便签内容，去除换行符和空格）
+ * - 搜索结果图标
+ * - 搜索结果的意图动作（查看）
+ * - 搜索结果的意图数据类型
+ *
+ *
+ * 特殊处理：
+ *
+ * - 使用SQLite函数TRIM和REPLACE去除便签内容中的换行符（x'0A'）和空格
+ * - 使用固定的搜索结果图标
+ *
*/
private static final String NOTES_SEARCH_PROJECTION = NoteColumns.ID + ","
+ NoteColumns.ID + " AS " + SearchManager.SUGGEST_COLUMN_INTENT_EXTRA_DATA + ","
@@ -73,18 +188,91 @@ public class NotesProvider extends ContentProvider {
+ "'" + Intent.ACTION_VIEW + "' AS " + SearchManager.SUGGEST_COLUMN_INTENT_ACTION + ","
+ "'" + Notes.TextNote.CONTENT_TYPE + "' AS " + SearchManager.SUGGEST_COLUMN_INTENT_DATA;
+ /**
+ * 便签搜索的SQL查询语句，用于执行实际的搜索操作
+ *
+ * 查询条件：
+ *
+ * - 便签内容包含搜索关键字（LIKE ?）
+ * - 便签不在回收站中（PARENT_ID <> TRASH_FOLDER）
+ * - 便签类型为普通便签（TYPE = TYPE_NOTE）
+ *
+ *
+ * 用途：在URI_SEARCH和URI_SEARCH_SUGGEST类型的请求中执行搜索操作
+ */
private static String NOTES_SNIPPET_SEARCH_QUERY = "SELECT " + NOTES_SEARCH_PROJECTION
+ " FROM " + TABLE.NOTE
+ " WHERE " + NoteColumns.SNIPPET + " LIKE ?"
+ " AND " + NoteColumns.PARENT_ID + "<>" + Notes.ID_TRASH_FOLER
+ " AND " + NoteColumns.TYPE + "=" + Notes.TYPE_NOTE;
+ /**
+ * 初始化Content Provider
+ *
+ * 业务逻辑：
+ *
+ * - 获取NotesDatabaseHelper的单例实例
+ * - 初始化数据库连接
+ *
+ *
+ * 与其他类的交互：
+ *
+ * - 调用{@link NotesDatabaseHelper#getInstance(android.content.Context)}获取数据库辅助类实例
+ *
+ *
+ * @return true 初始化成功
+ * @see android.content.ContentProvider#onCreate()
+ */
@Override
public boolean onCreate() {
mHelper = NotesDatabaseHelper.getInstance(getContext());
return true;
}
+ /**
+ * 处理查询请求，根据URI类型返回相应的Cursor对象
+ *
+ * 业务逻辑：
+ *
+ * - 根据URI类型分发到不同的查询逻辑
+ * - 获取可读数据库实例
+ * - 执行查询操作，返回Cursor对象
+ * - 为Cursor设置通知URI，以便数据变更时接收通知
+ *
+ *
+ * URI类型处理：
+ *
+ * - {@link #URI_NOTE} - 查询所有便签和文件夹
+ * - {@link #URI_NOTE_ITEM} - 查询单个便签或文件夹
+ * - {@link #URI_DATA} - 查询所有便签详细数据
+ * - {@link #URI_DATA_ITEM} - 查询单个便签详细数据
+ * - {@link #URI_SEARCH} - 执行便签搜索
+ * - {@link #URI_SEARCH_SUGGEST} - 提供搜索建议
+ *
+ *
+ * 与其他类的交互：
+ *
+ * - 使用{@link NotesDatabaseHelper#getReadableDatabase()}获取可读数据库
+ * - 使用{@link SQLiteDatabase}执行查询操作
+ * - 使用{@link SearchManager}处理搜索相关请求
+ *
+ *
+ * 特殊处理：
+ *
+ * - 搜索请求不允许指定sortOrder和projection参数
+ * - 搜索结果会去除换行符和空格，以便显示更多信息
+ * - 搜索范围不包括回收站中的便签
+ *
+ *
+ * @param uri 请求的URI
+ * @param projection 返回的列名数组
+ * @param selection 查询条件
+ * @param selectionArgs 查询条件参数
+ * @param sortOrder 排序方式
+ * @return Cursor 查询结果的Cursor对象，或null如果查询失败
+ * @throws IllegalArgumentException 如果URI无效或参数不符合要求
+ * @see android.content.ContentProvider#query(android.net.Uri, java.lang.String[], java.lang.String, java.lang.String[], java.lang.String)
+ */
@Override
public Cursor query(Uri uri, String[] projection, String selection, String[] selectionArgs,
String sortOrder) {
@@ -147,6 +335,43 @@ public class NotesProvider extends ContentProvider {
return c;
}
+ /**
+ * 处理插入请求，根据URI类型插入数据并返回新的URI
+ *
+ * 业务逻辑：
+ *
+ * - 根据URI类型分发到不同的插入逻辑
+ * - 获取可写数据库实例
+ * - 执行插入操作，返回插入的行ID
+ * - 通知相关URI的数据变更
+ * - 返回包含新ID的URI
+ *
+ *
+ * URI类型处理：
+ *
+ * - {@link #URI_NOTE} - 插入便签或文件夹
+ * - {@link #URI_DATA} - 插入便签详细数据
+ *
+ *
+ * 与其他类的交互：
+ *
+ * - 使用{@link NotesDatabaseHelper#getWritableDatabase()}获取可写数据库
+ * - 使用{@link SQLiteDatabase}执行插入操作
+ * - 通过{@link android.content.ContentResolver#notifyChange(android.net.Uri, android.database.ContentObserver)}通知数据变更
+ *
+ *
+ * 特殊处理：
+ *
+ * - 插入数据时，记录插入的noteId和dataId
+ * - 插入成功后，通知相关URI的数据变更
+ *
+ *
+ * @param uri 请求的URI
+ * @param values 要插入的数据
+ * @return Uri 包含新插入行ID的URI
+ * @throws IllegalArgumentException 如果URI无效
+ * @see android.content.ContentProvider#insert(android.net.Uri, android.content.ContentValues)
+ */
@Override
public Uri insert(Uri uri, ContentValues values) {
SQLiteDatabase db = mHelper.getWritableDatabase();
@@ -181,6 +406,45 @@ public class NotesProvider extends ContentProvider {
return ContentUris.withAppendedId(uri, insertedId);
}
+ /**
+ * 处理删除请求，根据URI类型删除数据并返回删除的行数
+ *
+ * 业务逻辑：
+ *
+ * - 根据URI类型分发到不同的删除逻辑
+ * - 获取可写数据库实例
+ * - 执行删除操作，返回删除的行数
+ * - 通知相关URI的数据变更
+ *
+ *
+ * URI类型处理：
+ *
+ * - {@link #URI_NOTE} - 删除便签或文件夹
+ * - {@link #URI_NOTE_ITEM} - 删除单个便签或文件夹
+ * - {@link #URI_DATA} - 删除便签详细数据
+ * - {@link #URI_DATA_ITEM} - 删除单个便签详细数据
+ *
+ *
+ * 与其他类的交互：
+ *
+ * - 使用{@link NotesDatabaseHelper#getWritableDatabase()}获取可写数据库
+ * - 使用{@link SQLiteDatabase}执行删除操作
+ * - 通过{@link android.content.ContentResolver#notifyChange(android.net.Uri, android.database.ContentObserver)}通知数据变更
+ *
+ *
+ * 特殊处理：
+ *
+ * - 删除便签时，跳过ID小于等于0的系统文件夹
+ * - 删除数据时，同时通知CONTENT_NOTE_URI的数据变更
+ *
+ *
+ * @param uri 请求的URI
+ * @param selection 删除条件
+ * @param selectionArgs 删除条件参数
+ * @return int 删除的行数
+ * @throws IllegalArgumentException 如果URI无效
+ * @see android.content.ContentProvider#delete(android.net.Uri, java.lang.String, java.lang.String[])
+ */
@Override
public int delete(Uri uri, String selection, String[] selectionArgs) {
int count = 0;
@@ -227,6 +491,48 @@ public class NotesProvider extends ContentProvider {
return count;
}
+ /**
+ * 处理更新请求，根据URI类型更新数据并返回更新的行数
+ *
+ * 业务逻辑：
+ *
+ * - 根据URI类型分发到不同的更新逻辑
+ * - 获取可写数据库实例
+ * - 对于便签更新，先增加版本号
+ * - 执行更新操作，返回更新的行数
+ * - 通知相关URI的数据变更
+ *
+ *
+ * URI类型处理：
+ *
+ * - {@link #URI_NOTE} - 更新便签或文件夹
+ * - {@link #URI_NOTE_ITEM} - 更新单个便签或文件夹
+ * - {@link #URI_DATA} - 更新便签详细数据
+ * - {@link #URI_DATA_ITEM} - 更新单个便签详细数据
+ *
+ *
+ * 与其他类的交互：
+ *
+ * - 使用{@link NotesDatabaseHelper#getWritableDatabase()}获取可写数据库
+ * - 使用{@link SQLiteDatabase}执行更新操作
+ * - 调用{@link #increaseNoteVersion(long, String, String[])}增加便签版本号
+ * - 通过{@link android.content.ContentResolver#notifyChange(android.net.Uri, android.database.ContentObserver)}通知数据变更
+ *
+ *
+ * 特殊处理：
+ *
+ * - 更新便签时，自动增加版本号
+ * - 更新数据时，同时通知CONTENT_NOTE_URI的数据变更
+ *
+ *
+ * @param uri 请求的URI
+ * @param values 要更新的数据
+ * @param selection 更新条件
+ * @param selectionArgs 更新条件参数
+ * @return int 更新的行数
+ * @throws IllegalArgumentException 如果URI无效
+ * @see android.content.ContentProvider#update(android.net.Uri, android.content.ContentValues, java.lang.String, java.lang.String[])
+ */
@Override
public int update(Uri uri, ContentValues values, String selection, String[] selectionArgs) {
int count = 0;
@@ -267,10 +573,49 @@ public class NotesProvider extends ContentProvider {
return count;
}
+ /**
+ * 辅助方法，处理查询条件，将额外条件添加到现有条件中
+ *
+ * 业务逻辑：
+ *
+ * - 如果selection不为空，将其包装为" AND (selection)"格式
+ * - 否则返回空字符串
+ *
+ *
+ * @param selection 原始查询条件
+ * @return String 处理后的查询条件
+ */
private String parseSelection(String selection) {
return (!TextUtils.isEmpty(selection) ? " AND (" + selection + ')' : "");
}
+ /**
+ * 辅助方法，增加便签的版本号
+ *
+ * 业务逻辑：
+ *
+ * - 构建UPDATE语句，将版本号加1
+ * - 根据id和selection参数构建WHERE子句
+ * - 执行SQL语句，更新版本号
+ *
+ *
+ * 与其他类的交互：
+ *
+ * - 使用{@link NotesDatabaseHelper#getWritableDatabase()}获取可写数据库
+ * - 使用{@link SQLiteDatabase#execSQL(String)}执行SQL语句
+ *
+ *
+ * 特殊处理：
+ *
+ * - 直接使用字符串拼接构建SQL语句，存在SQL注入风险
+ * - 使用replaceFirst替换占位符，仅适用于简单的条件
+ * - TODO: 考虑使用PreparedStatement或参数化查询，提高安全性
+ *
+ *
+ * @param id 便签ID，-1表示更新多个便签
+ * @param selection 更新条件
+ * @param selectionArgs 更新条件参数
+ */
private void increaseNoteVersion(long id, String selection, String[] selectionArgs) {
StringBuilder sql = new StringBuilder(120);
sql.append("UPDATE ");
@@ -296,6 +641,17 @@ public class NotesProvider extends ContentProvider {
mHelper.getWritableDatabase().execSQL(sql.toString());
}
+ /**
+ * 获取URI对应的MIME类型
+ *
+ * 注意：该方法目前未实现，返回null
+ *
+ * TODO: 实现该方法，返回正确的MIME类型
+ *
+ * @param uri 请求的URI
+ * @return String URI对应的MIME类型，目前返回null
+ * @see android.content.ContentProvider#getType(android.net.Uri)
+ */
@Override
public String getType(Uri uri) {
// TODO Auto-generated method stub
diff --git a/src/gtask/data/MetaData.java b/src/gtask/data/MetaData.java
index 3a2050b..211f917 100644
--- a/src/gtask/data/MetaData.java
+++ b/src/gtask/data/MetaData.java
@@ -25,11 +25,57 @@ import org.json.JSONException;
import org.json.JSONObject;
+/**
+ *
任务元数据管理类，用于存储Google任务的元数据信息。
+ * 核心职责：
+ *
+ * - 存储和管理任务的元数据信息
+ * - 处理元数据的JSON序列化和反序列化
+ * - 管理与其他任务的关联关系
+ *
+ * 设计意图：
+ *
+ * - 继承自{@link Task}类，扩展其功能以支持元数据管理
+ * - 使用JSON格式存储元数据，便于序列化和传输
+ * - 提供元数据的设置和获取接口，简化元数据操作
+ *
+ * 关键关联：
+ *
+ * - 继承自{@link Task}类，复用任务的基本功能
+ * - 使用{@link GTaskStringUtils}提供的常量定义元数据格式
+ * - 被{@link GTaskManager}和{@link GTaskSyncService}使用，管理任务同步元数据
+ *
+ */
public class MetaData extends Task {
+ /**
+ * 日志标签。
+ * 业务含义：用于在日志中标识MetaData类的相关操作。
+ */
private final static String TAG = MetaData.class.getSimpleName();
+ /**
+ * 关联的Google任务ID。
+ * 业务含义：存储与当前元数据相关联的Google任务的唯一标识符。
+ * 约束条件：仅通过{@link #setContentByRemoteJSON(JSONObject)}方法从远程JSON数据中获取。
+ */
private String mRelatedGid = null;
+ /**
+ * 设置任务元数据信息。
+ * 业务逻辑：
+ *
+ * - 将Google任务ID添加到元数据JSON对象中
+ * - 将元数据JSON对象转换为字符串，存储到任务的notes字段中
+ * - 设置任务名称为元数据专用名称
+ *
+ * 异常处理：
+ *
+ * - 处理JSONException异常，如果添加Google任务ID失败，记录错误日志
+ *
+ *
+ * @param gid 关联的Google任务ID
+ * @param metaInfo 元数据JSON对象
+ */
public void setMeta(String gid, JSONObject metaInfo) {
try {
metaInfo.put(GTaskStringUtils.META_HEAD_GTASK_ID, gid);
@@ -40,15 +86,42 @@ public class MetaData extends Task {
setName(GTaskStringUtils.META_NOTE_NAME);
}
+ /**
+ * 获取关联的Google任务ID。
+ * 业务含义：返回与当前元数据相关联的Google任务的唯一标识符。
+ *
+ * @return 关联的Google任务ID，如果不存在则返回null
+ */
public String getRelatedGid() {
return mRelatedGid;
}
+ /**
+ * 判断元数据是否值得保存。
+ * 业务逻辑：如果元数据的notes字段不为null，则认为值得保存。
+ *
+ * @return 如果元数据值得保存则返回true，否则返回false
+ */
@Override
public boolean isWorthSaving() {
return getNotes() != null;
}
+ /**
+ * 根据远程JSON数据设置元数据内容。
+ * 业务逻辑：
+ *
+ * - 调用父类的setContentByRemoteJSON方法设置基本任务内容
+ * - 如果notes字段不为null，则解析JSON字符串获取元数据信息
+ * - 从元数据中提取关联的Google任务ID
+ *
+ * 异常处理：
+ *
+ * - 处理JSONException异常，如果解析元数据失败，记录警告日志并将mRelatedGid设置为null
+ *
+ *
+ * @param js 远程JSON数据对象
+ */
@Override
public void setContentByRemoteJSON(JSONObject js) {
super.setContentByRemoteJSON(js);
@@ -63,17 +136,42 @@ public class MetaData extends Task {
}
}
+ /**
+ * 根据本地JSON数据设置元数据内容。
+ * 业务逻辑：此方法不应被调用，直接抛出IllegalAccessError异常。
+ * 注意：MetaData类不支持从本地JSON数据设置内容。
+ *
+ * @param js 本地JSON数据对象
+ * @throws IllegalAccessError 总是抛出此异常，因为该方法不应被调用
+ */
@Override
public void setContentByLocalJSON(JSONObject js) {
// this function should not be called
throw new IllegalAccessError("MetaData:setContentByLocalJSON should not be called");
}
+ /**
+ * 从元数据内容获取本地JSON对象。
+ * 业务逻辑：此方法不应被调用，直接抛出IllegalAccessError异常。
+ * 注意：MetaData类不支持获取本地JSON数据。
+ *
+ * @return 本地JSON数据对象
+ * @throws IllegalAccessError 总是抛出此异常，因为该方法不应被调用
+ */
@Override
public JSONObject getLocalJSONFromContent() {
throw new IllegalAccessError("MetaData:getLocalJSONFromContent should not be called");
}
+ /**
+ * 获取元数据的同步操作类型。
+ * 业务逻辑：此方法不应被调用，直接抛出IllegalAccessError异常。
+ * 注意：MetaData类不支持获取同步操作类型。
+ *
+ * @param c 数据库游标对象
+ * @return 同步操作类型
+ * @throws IllegalAccessError 总是抛出此异常，因为该方法不应被调用
+ */
@Override
public int getSyncAction(Cursor c) {
throw new IllegalAccessError("MetaData:getSyncAction should not be called");
diff --git a/src/gtask/data/Node.java b/src/gtask/data/Node.java
index 63950e0..ea764ec 100644
--- a/src/gtask/data/Node.java
+++ b/src/gtask/data/Node.java
@@ -20,33 +20,91 @@ import android.database.Cursor;
import org.json.JSONObject;
+/**
+ * Google任务数据模型的抽象基类。
+ * 设计意图：统一定义Google任务相关数据（如任务、元数据）的核心属性和同步行为，为子类提供标准化接口。
+ * 核心职责：
+ *
+ * - 封装通用属性：Google任务ID（GID）、名称、最后修改时间、删除状态
+ * - 定义同步操作抽象方法：创建/更新动作生成、本地/远程JSON数据转换、同步动作判断
+ * - 提供同步动作常量：规范同步操作类型（无动作、添加、更新、删除、冲突等）
+ *
+ * 关键关联：
+ *
+ * - 子类需实现抽象方法以适配具体数据类型（如{@link Task}, {@link MetaData}）
+ * - 与{@link GTaskClient}配合完成Google任务服务的同步操作
+ * - 通过{@link Cursor}与本地数据库交互获取同步状态
+ *
+ */
public abstract class Node {
+ /**
+ * 无同步动作
+ */
public static final int SYNC_ACTION_NONE = 0;
+ /**
+ * 向远程添加任务
+ */
public static final int SYNC_ACTION_ADD_REMOTE = 1;
+ /**
+ * 向本地添加任务
+ */
public static final int SYNC_ACTION_ADD_LOCAL = 2;
+ /**
+ * 删除远程任务
+ */
public static final int SYNC_ACTION_DEL_REMOTE = 3;
+ /**
+ * 删除本地任务
+ */
public static final int SYNC_ACTION_DEL_LOCAL = 4;
+ /**
+ * 更新远程任务
+ */
public static final int SYNC_ACTION_UPDATE_REMOTE = 5;
+ /**
+ * 更新本地任务
+ */
public static final int SYNC_ACTION_UPDATE_LOCAL = 6;
+ /**
+ * 更新冲突（本地与远程同时修改）
+ */
public static final int SYNC_ACTION_UPDATE_CONFLICT = 7;
+ /**
+ * 同步错误状态
+ */
public static final int SYNC_ACTION_ERROR = 8;
+ /**
+ * Google任务唯一标识ID，约束条件：仅通过远程同步设置
+ */
private String mGid;
+ /**
+ * 任务名称
+ */
private String mName;
+ /**
+ * 最后修改时间戳（毫秒）
+ */
private long mLastModified;
+ /**
+ * 删除状态标记
+ */
private boolean mDeleted;
+ /**
+ * 默认构造方法，初始化默认值
+ */
public Node() {
mGid = null;
mName = "";
@@ -54,46 +112,134 @@ public abstract class Node {
mDeleted = false;
}
+ /**
+ * 生成创建动作的JSON对象。
+ * 业务逻辑：构造用于向Google任务服务添加新任务的JSON数据。
+ *
+ * @param actionId 动作ID，用于标识同步任务序列
+ * @return 创建动作的JSON对象，包含必要的元数据和内容信息
+ */
public abstract JSONObject getCreateAction(int actionId);
+ /**
+ * 生成更新动作的JSON对象。
+ * 业务逻辑：构造用于向Google任务服务更新现有任务的JSON数据。
+ *
+ * @param actionId 动作ID，用于标识同步任务序列
+ * @return 更新动作的JSON对象，包含待更新的字段和内容
+ */
public abstract JSONObject getUpdateAction(int actionId);
+ /**
+ * 从远程JSON数据解析并设置内容。
+ * 业务逻辑：将Google任务服务返回的JSON数据转换为本地对象属性。
+ *
+ * @param js 远程获取的JSON对象，包含Google任务服务返回的任务数据
+ */
public abstract void setContentByRemoteJSON(JSONObject js);
+ /**
+ * 从本地JSON数据解析并设置内容。
+ * 业务逻辑：将本地存储的JSON数据转换为对象属性。
+ *
+ * @param js 本地存储的JSON对象，包含应用内持久化的任务数据
+ */
public abstract void setContentByLocalJSON(JSONObject js);
+ /**
+ * 将当前内容转换为本地存储用的JSON对象。
+ * 业务逻辑：将对象属性转换为可持久化到本地数据库的JSON格式。
+ *
+ * @return 包含内容数据的JSON对象，用于本地持久化
+ */
public abstract JSONObject getLocalJSONFromContent();
+ /**
+ * 从数据库游标判断当前同步动作类型。
+ * 业务逻辑：比较本地数据库与远程同步状态，确定需要执行的同步操作类型。
+ * 可能的返回值：
+ *
+ * - {@link #SYNC_ACTION_NONE}：无需同步
+ * - {@link #SYNC_ACTION_ADD_REMOTE}：向远程添加
+ * - {@link #SYNC_ACTION_UPDATE_LOCAL}：更新本地
+ * - {@link #SYNC_ACTION_UPDATE_CONFLICT}：更新冲突
+ * - 等其他同步动作常量
+ *
+ *
+ *
+ * @param c 查询本地数据库得到的游标，包含任务的同步状态信息
+ * @return 同步动作类型，取值为{@link #SYNC_ACTION_NONE}至{@link #SYNC_ACTION_ERROR}
+ */
public abstract int getSyncAction(Cursor c);
+ /**
+ * 设置Google任务唯一标识ID
+ *
+ * @param gid Google任务ID
+ */
public void setGid(String gid) {
this.mGid = gid;
}
+ /**
+ * 设置任务名称
+ *
+ * @param name 任务名称
+ */
public void setName(String name) {
this.mName = name;
}
+ /**
+ * 设置最后修改时间戳
+ *
+ * @param lastModified 最后修改时间（毫秒）
+ */
public void setLastModified(long lastModified) {
this.mLastModified = lastModified;
}
+ /**
+ * 设置任务删除状态
+ *
+ * @param deleted 删除状态
+ */
public void setDeleted(boolean deleted) {
this.mDeleted = deleted;
}
+ /**
+ * 获取Google任务唯一标识ID
+ *
+ * @return Google任务ID
+ */
public String getGid() {
return this.mGid;
}
+ /**
+ * 获取任务名称
+ *
+ * @return 任务名称
+ */
public String getName() {
return this.mName;
}
+ /**
+ * 获取最后修改时间戳
+ *
+ * @return 最后修改时间（毫秒）
+ */
public long getLastModified() {
return this.mLastModified;
}
+ /**
+ * 判断任务是否已删除
+ *
+ * @return 是否已删除
+ */
public boolean getDeleted() {
return this.mDeleted;
}
diff --git a/src/gtask/data/SqlData.java b/src/gtask/data/SqlData.java
index d3ec3be..3bd6934 100644
--- a/src/gtask/data/SqlData.java
+++ b/src/gtask/data/SqlData.java
@@ -35,42 +35,103 @@ import org.json.JSONException;
import org.json.JSONObject;
+/**
+ * SQL数据操作类，用于处理便签数据的增删改查操作。
+ * 设计意图：作为Google任务同步与本地数据库之间的数据操作桥梁，封装对ContentProvider的访问。
+ * 核心职责：
+ *
+ * - 从Cursor加载数据
+ * - 与JSON数据格式的相互转换
+ * - 将数据变更提交到ContentProvider
+ * - 跟踪数据变更差异
+ *
+ */
public class SqlData {
private static final String TAG = SqlData.class.getSimpleName();
+ /**
+ * 无效ID常量
+ */
private static final int INVALID_ID = -99999;
+ /**
+ * 数据查询投影列
+ */
public static final String[] PROJECTION_DATA = new String[] {
DataColumns.ID, DataColumns.MIME_TYPE, DataColumns.CONTENT, DataColumns.DATA1,
DataColumns.DATA3
};
+ /**
+ * 数据ID列索引
+ */
public static final int DATA_ID_COLUMN = 0;
+ /**
+ * 数据MIME类型列索引
+ */
public static final int DATA_MIME_TYPE_COLUMN = 1;
+ /**
+ * 数据内容列索引
+ */
public static final int DATA_CONTENT_COLUMN = 2;
+ /**
+ * 数据内容DATA1列索引
+ */
public static final int DATA_CONTENT_DATA_1_COLUMN = 3;
+ /**
+ * 数据内容DATA3列索引
+ */
public static final int DATA_CONTENT_DATA_3_COLUMN = 4;
+ /**
+ * 内容解析器，用于访问ContentProvider
+ */
private ContentResolver mContentResolver;
+ /**
+ * 是否为新创建的数据
+ */
private boolean mIsCreate;
+ /**
+ * 数据ID
+ */
private long mDataId;
+ /**
+ * 数据MIME类型
+ */
private String mDataMimeType;
+ /**
+ * 数据内容
+ */
private String mDataContent;
+ /**
+ * 数据内容DATA1字段
+ */
private long mDataContentData1;
+ /**
+ * 数据内容DATA3字段
+ */
private String mDataContentData3;
+ /**
+ * 数据变更差异集合
+ */
private ContentValues mDiffDataValues;
+ /**
+ * 构造方法，创建新的SqlData对象。
+ *
+ * @param context 上下文对象
+ */
public SqlData(Context context) {
mContentResolver = context.getContentResolver();
mIsCreate = true;
@@ -82,6 +143,12 @@ public class SqlData {
mDiffDataValues = new ContentValues();
}
+ /**
+ * 构造方法，从Cursor创建SqlData对象。
+ *
+ * @param context 上下文对象
+ * @param c 包含数据的Cursor对象
+ */
public SqlData(Context context, Cursor c) {
mContentResolver = context.getContentResolver();
mIsCreate = false;
@@ -89,6 +156,11 @@ public class SqlData {
mDiffDataValues = new ContentValues();
}
+ /**
+ * 从Cursor加载数据到当前对象。
+ *
+ * @param c 包含数据的Cursor对象
+ */
private void loadFromCursor(Cursor c) {
mDataId = c.getLong(DATA_ID_COLUMN);
mDataMimeType = c.getString(DATA_MIME_TYPE_COLUMN);
@@ -97,6 +169,18 @@ public class SqlData {
mDataContentData3 = c.getString(DATA_CONTENT_DATA_3_COLUMN);
}
+ /**
+ * 从JSON对象设置数据内容。
+ * 业务逻辑：
+ *
+ * - 从JSON对象中提取各个字段的值
+ * - 比较当前值与新值，仅在不同时更新差异集合
+ * - 更新当前对象的字段值
+ *
+ *
+ * @param js 包含数据的JSON对象
+ * @throws JSONException 如果JSON解析失败
+ */
public void setContent(JSONObject js) throws JSONException {
long dataId = js.has(DataColumns.ID) ? js.getLong(DataColumns.ID) : INVALID_ID;
if (mIsCreate || mDataId != dataId) {
@@ -130,6 +214,18 @@ public class SqlData {
mDataContentData3 = dataContentData3;
}
+ /**
+ * 获取当前数据的JSON表示。
+ * 业务逻辑：
+ *
+ * - 检查数据是否已创建
+ * - 创建JSON对象并设置各个字段值
+ * - 返回JSON对象
+ *
+ *
+ * @return 包含数据的JSON对象，若数据未创建则返回null
+ * @throws JSONException 如果JSON创建失败
+ */
public JSONObject getContent() throws JSONException {
if (mIsCreate) {
Log.e(TAG, "it seems that we haven't created this in database yet");
@@ -144,6 +240,21 @@ public class SqlData {
return js;
}
+ /**
+ * 提交数据变更到ContentProvider。
+ * 业务逻辑：
+ *
+ * - 如果是新创建的数据，执行插入操作
+ * - 如果是已存在的数据，执行更新操作
+ * - 支持版本验证，避免并发更新冲突
+ * - 更新操作完成后清空差异集合
+ *
+ *
+ * @param noteId 所属便签ID
+ * @param validateVersion 是否验证版本
+ * @param version 版本号
+ * @throws ActionFailureException 如果操作失败
+ */
public void commit(long noteId, boolean validateVersion, long version) {
if (mIsCreate) {
@@ -183,6 +294,11 @@ public class SqlData {
mIsCreate = false;
}
+ /**
+ * 获取数据ID。
+ *
+ * @return 数据ID
+ */
public long getId() {
return mDataId;
}
diff --git a/src/gtask/data/SqlNote.java b/src/gtask/data/SqlNote.java
index 79a4095..721703c 100644
--- a/src/gtask/data/SqlNote.java
+++ b/src/gtask/data/SqlNote.java
@@ -38,11 +38,50 @@ import org.json.JSONObject;
import java.util.ArrayList;
+/**
+ * 本地便签数据操作类，用于Google任务同步时的便签元数据与内容数据管理。
+ * 核心职责：
+ *
+ * - 管理便签的元数据（如标题、类型、修改时间等）
+ * - 处理便签的内容数据集合（通过{@link SqlData}）
+ * - 实现便签数据与JSON格式的相互转换
+ * - 提供便签数据的增删改查操作
+ * - 支持版本验证以避免并发更新冲突
+ *
+ * 设计意图：
+ *
+ * - 作为Google任务同步与本地数据库之间的桥梁
+ * - 封装ContentProvider的复杂操作，提供简洁的API
+ * - 支持批量提交数据变更，提高性能
+ * - 维护数据一致性，确保元数据与内容数据同步更新
+ *
+ * 关键关联：
+ *
+ * - 使用{@link Context}访问系统ContentResolver
+ * - 使用{@link ContentProvider}进行本地数据库操作
+ * - 与{@link SqlData}协作管理便签内容
+ * - 与{@link GTaskManager}集成实现Google任务同步
+ *
+ */
public class SqlNote {
+ /**
+ * 日志标签。
+ * 业务含义：用于在日志中标识SqlNote类的相关操作，便于调试和问题追踪。
+ */
private static final String TAG = SqlNote.class.getSimpleName();
+ /**
+ * 无效ID常量。
+ * 业务含义：表示未初始化或无效的便签ID，用于边界条件判断。
+ * 取值：-99999
+ */
private static final int INVALID_ID = -99999;
+ /**
+ * 便签查询投影列。
+ * 业务含义：定义从ContentProvider查询便签数据时返回的字段集合。
+ * 包含：ID、提醒日期、背景颜色ID、创建日期、是否有附件、修改日期等关键字段。
+ */
public static final String[] PROJECTION_NOTE = new String[] {
NoteColumns.ID, NoteColumns.ALERTED_DATE, NoteColumns.BG_COLOR_ID,
NoteColumns.CREATED_DATE, NoteColumns.HAS_ATTACHMENT, NoteColumns.MODIFIED_DATE,
@@ -52,76 +91,264 @@ public class SqlNote {
NoteColumns.VERSION
};
+ /**
+ * ID列索引。
+ * 业务含义：PROJECTION_NOTE数组中ID字段的索引位置。
+ * 取值：0
+ */
public static final int ID_COLUMN = 0;
+ /**
+ * 提醒日期列索引。
+ * 业务含义：PROJECTION_NOTE数组中提醒日期字段的索引位置。
+ * 取值：1
+ */
public static final int ALERTED_DATE_COLUMN = 1;
+ /**
+ * 背景颜色ID列索引。
+ * 业务含义：PROJECTION_NOTE数组中背景颜色ID字段的索引位置。
+ * 取值：2
+ */
public static final int BG_COLOR_ID_COLUMN = 2;
+ /**
+ * 创建日期列索引。
+ * 业务含义：PROJECTION_NOTE数组中创建日期字段的索引位置。
+ * 取值：3
+ */
public static final int CREATED_DATE_COLUMN = 3;
+ /**
+ * 是否有附件列索引。
+ * 业务含义：PROJECTION_NOTE数组中是否有附件字段的索引位置。
+ * 取值：4
+ */
public static final int HAS_ATTACHMENT_COLUMN = 4;
+ /**
+ * 修改日期列索引。
+ * 业务含义：PROJECTION_NOTE数组中修改日期字段的索引位置。
+ * 取值：5
+ */
public static final int MODIFIED_DATE_COLUMN = 5;
+ /**
+ * 便签数量列索引。
+ * 业务含义：PROJECTION_NOTE数组中便签数量字段的索引位置。
+ * 取值：6
+ */
public static final int NOTES_COUNT_COLUMN = 6;
+ /**
+ * 父ID列索引。
+ * 业务含义：PROJECTION_NOTE数组中父ID字段的索引位置。
+ * 取值：7
+ */
public static final int PARENT_ID_COLUMN = 7;
+ /**
+ * 摘要列索引。
+ * 业务含义：PROJECTION_NOTE数组中摘要字段的索引位置。
+ * 取值：8
+ */
public static final int SNIPPET_COLUMN = 8;
+ /**
+ * 类型列索引。
+ * 业务含义：PROJECTION_NOTE数组中类型字段的索引位置。
+ * 取值：9
+ */
public static final int TYPE_COLUMN = 9;
+ /**
+ * 小组件ID列索引。
+ * 业务含义：PROJECTION_NOTE数组中小组件ID字段的索引位置。
+ * 取值：10
+ */
public static final int WIDGET_ID_COLUMN = 10;
+ /**
+ * 小组件类型列索引。
+ * 业务含义：PROJECTION_NOTE数组中小组件类型字段的索引位置。
+ * 取值：11
+ */
public static final int WIDGET_TYPE_COLUMN = 11;
+ /**
+ * 同步ID列索引。
+ * 业务含义：PROJECTION_NOTE数组中同步ID字段的索引位置。
+ * 取值：12
+ */
public static final int SYNC_ID_COLUMN = 12;
+ /**
+ * 本地修改列索引。
+ * 业务含义：PROJECTION_NOTE数组中本地修改字段的索引位置。
+ * 取值：13
+ */
public static final int LOCAL_MODIFIED_COLUMN = 13;
+ /**
+ * 原始父ID列索引。
+ * 业务含义：PROJECTION_NOTE数组中原始父ID字段的索引位置。
+ * 取值：14
+ */
public static final int ORIGIN_PARENT_ID_COLUMN = 14;
+ /**
+ * Google任务ID列索引。
+ * 业务含义：PROJECTION_NOTE数组中Google任务ID字段的索引位置。
+ * 取值：15
+ */
public static final int GTASK_ID_COLUMN = 15;
+ /**
+ * 版本列索引。
+ * 业务含义：PROJECTION_NOTE数组中版本字段的索引位置。
+ * 取值：16
+ */
public static final int VERSION_COLUMN = 16;
+ /**
+ * 上下文对象。
+ * 业务含义：用于访问系统资源和ContentResolver。
+ * 使用场景：在构造函数中初始化，用于后续的ContentProvider操作。
+ */
private Context mContext;
+ /**
+ * 内容解析器。
+ * 业务含义：用于与ContentProvider进行交互，执行数据库操作。
+ * 使用场景：在构造函数中初始化，用于后续的CRUD操作。
+ */
private ContentResolver mContentResolver;
+ /**
+ * 是否为新创建的便签。
+ * 业务含义：标识当前便签对象是否已在数据库中创建。
+ * 使用场景：在构造函数中初始化，用于确定执行插入或更新操作。
+ */
private boolean mIsCreate;
+ /**
+ * 便签ID。
+ * 业务含义：便签在本地数据库中的唯一标识符。
+ * 默认值：INVALID_ID（-99999）
+ */
private long mId;
+ /**
+ * 提醒日期。
+ * 业务含义：便签的提醒时间戳。
+ * 默认值：0（表示无提醒）
+ */
private long mAlertDate;
+ /**
+ * 背景颜色ID。
+ * 业务含义：便签的背景颜色资源ID。
+ * 默认值：通过ResourceParser.getDefaultBgId(context)获取
+ */
private int mBgColorId;
+ /**
+ * 创建日期。
+ * 业务含义：便签创建的时间戳。
+ * 默认值：当前系统时间
+ */
private long mCreatedDate;
+ /**
+ * 是否有附件。
+ * 业务含义：标识便签是否包含附件。
+ * 取值：0（无附件）或1（有附件）
+ * 默认值：0
+ */
private int mHasAttachment;
+ /**
+ * 修改日期。
+ * 业务含义：便签最后一次修改的时间戳。
+ * 默认值：当前系统时间
+ */
private long mModifiedDate;
+ /**
+ * 父便签ID。
+ * 业务含义：便签所属的父文件夹ID。
+ * 默认值：0（表示根目录）
+ */
private long mParentId;
+ /**
+ * 便签摘要。
+ * 业务含义：便签的标题或简短描述。
+ * 默认值：空字符串
+ */
private String mSnippet;
+ /**
+ * 便签类型。
+ * 业务含义：便签的类型（如普通便签、文件夹等）。
+ * 默认值：Notes.TYPE_NOTE
+ */
private int mType;
+ /**
+ * 小组件ID。
+ * 业务含义：关联的桌面小组件ID。
+ * 默认值：AppWidgetManager.INVALID_APPWIDGET_ID
+ */
private int mWidgetId;
+ /**
+ * 小组件类型。
+ * 业务含义：关联的桌面小组件类型。
+ * 默认值：Notes.TYPE_WIDGET_INVALIDE
+ */
private int mWidgetType;
+ /**
+ * 原始父便签ID。
+ * 业务含义：便签原始所属的父文件夹ID，用于同步操作。
+ * 默认值：0
+ */
private long mOriginParent;
+ /**
+ * 版本号。
+ * 业务含义：便签的版本号，用于并发更新冲突检测。
+ * 默认值：0
+ */
private long mVersion;
+ /**
+ * 便签元数据变更集合。
+ * 业务含义：存储便签元数据的变更内容，用于批量更新。
+ * 使用场景：在setContent方法中记录变更，在commit方法中提交变更。
+ */
private ContentValues mDiffNoteValues;
+ /**
+ * 便签内容数据集合。
+ * 业务含义：存储便签的内容数据列表。
+ * 使用场景：与SqlData类协作，管理便签的具体内容。
+ */
private ArrayList mDataList;
+ /**
+ * 创建一个新的SqlNote实例。
+ * 功能：初始化一个新的便签对象，设置默认值。
+ * 业务逻辑：
+ *
+ * - 设置mIsCreate为true，表示这是一个新创建的便签
+ * - 初始化所有字段为默认值
+ * - 创建空的变更集合和数据列表
+ *
+ *
+ * @param context 上下文对象，用于访问系统资源和ContentResolver
+ */
public SqlNote(Context context) {
mContext = context;
mContentResolver = context.getContentResolver();
@@ -143,6 +370,20 @@ public class SqlNote {
mDataList = new ArrayList();
}
+ /**
+ * 从Cursor创建SqlNote实例。
+ * 功能：从数据库查询结果创建便签对象。
+ * 业务逻辑：
+ *
+ * - 设置mIsCreate为false，表示这是一个已存在的便签
+ * - 从Cursor加载便签数据
+ * - 如果是普通便签，加载便签内容
+ * - 创建空的变更集合
+ *
+ *
+ * @param context 上下文对象，用于访问系统资源和ContentResolver
+ * @param c 查询结果Cursor，包含便签的元数据
+ */
public SqlNote(Context context, Cursor c) {
mContext = context;
mContentResolver = context.getContentResolver();
@@ -154,6 +395,20 @@ public class SqlNote {
mDiffNoteValues = new ContentValues();
}
+ /**
+ * 通过ID创建SqlNote实例。
+ * 功能：根据便签ID从数据库加载便签对象。
+ * 业务逻辑：
+ *
+ * - 设置mIsCreate为false，表示这是一个已存在的便签
+ * - 根据ID查询数据库并加载便签数据
+ * - 如果是普通便签，加载便签内容
+ * - 创建空的变更集合
+ *
+ *
+ * @param context 上下文对象，用于访问系统资源和ContentResolver
+ * @param id 便签ID，用于从数据库加载便签数据
+ */
public SqlNote(Context context, long id) {
mContext = context;
mContentResolver = context.getContentResolver();
@@ -163,7 +418,6 @@ public class SqlNote {
if (mType == Notes.TYPE_NOTE)
loadDataContent();
mDiffNoteValues = new ContentValues();
-
}
private void loadFromCursor(long id) {
diff --git a/src/gtask/data/Task.java b/src/gtask/data/Task.java
index 6a19454..49c23b2 100644
--- a/src/gtask/data/Task.java
+++ b/src/gtask/data/Task.java
@@ -32,19 +32,55 @@ import org.json.JSONException;
import org.json.JSONObject;
+/**
+ * Google任务类，继承自{@link Node}抽象类。
+ * 设计意图：实现Google任务的具体数据模型和同步操作，处理任务的创建、更新、删除等功能。
+ * 核心职责：
+ *
+ * - 封装Google任务的特有属性：完成状态、备注、元信息、兄弟任务关系、父子任务关系
+ * - 实现同步操作方法：生成创建/更新动作、解析本地/远程JSON数据、判断同步动作类型
+ * - 提供任务关系管理：设置父任务列表、前一个兄弟任务
+ * - 实现任务元信息管理：设置和解析任务的元数据
+ *
+ * 关键关联：
+ *
+ * - 继承自{@link Node}抽象类，实现Google任务数据模型的标准化接口
+ * - 与{@link TaskList}类关联，任务必须属于某个任务列表
+ * - 与{@link MetaData}类关联，管理任务的元信息
+ * - 与{@link GTaskStringUtils}类配合使用，处理Google任务的JSON字段名
+ *
+ */
public class Task extends Node {
private static final String TAG = Task.class.getSimpleName();
+ /**
+ * 任务完成状态标记
+ */
private boolean mCompleted;
+ /**
+ * 任务备注信息
+ */
private String mNotes;
+ /**
+ * 任务元信息JSON对象，包含本地任务的详细信息
+ */
private JSONObject mMetaInfo;
+ /**
+ * 前一个兄弟任务，用于维护任务的顺序
+ */
private Task mPriorSibling;
+ /**
+ * 父任务列表，任务所属的任务列表
+ */
private TaskList mParent;
+ /**
+ * 默认构造方法，初始化任务属性
+ */
public Task() {
super();
mCompleted = false;
@@ -54,6 +90,26 @@ public class Task extends Node {
mMetaInfo = null;
}
+ /**
+ * 生成创建任务的JSON动作对象。
+ * 业务逻辑：构造用于向Google任务服务添加新任务的JSON数据，包含任务的基本信息和关系。
+ * JSON结构说明：
+ *
+ * - action_type: 动作类型，固定为"create"
+ * - action_id: 动作ID，用于标识同步任务序列
+ * - index: 任务在父列表中的位置索引
+ * - entity_delta: 任务实体信息，包含任务名称、创建者ID、实体类型、备注等
+ * - parent_id: 父任务列表ID
+ * - dest_parent_type: 目标父类型，固定为"group"
+ * - list_id: 任务列表ID
+ * - prior_sibling_id: 前一个兄弟任务ID（可选）
+ *
+ *
+ *
+ * @param actionId 动作ID，用于标识同步任务序列
+ * @return 创建动作的JSON对象，包含任务创建所需的所有信息
+ * @throws ActionFailureException 如果生成JSON对象失败，抛出此异常
+ */
public JSONObject getCreateAction(int actionId) {
JSONObject js = new JSONObject();
@@ -103,6 +159,22 @@ public class Task extends Node {
return js;
}
+ /**
+ * 生成更新任务的JSON动作对象。
+ * 业务逻辑：构造用于向Google任务服务更新现有任务的JSON数据，包含任务的更新信息。
+ * JSON结构说明：
+ *
+ * - action_type: 动作类型，固定为"update"
+ * - action_id: 动作ID，用于标识同步任务序列
+ * - id: 任务ID，标识要更新的任务
+ * - entity_delta: 任务实体更新信息，包含任务名称、备注、删除状态等
+ *
+ *
+ *
+ * @param actionId 动作ID，用于标识同步任务序列
+ * @return 更新动作的JSON对象，包含任务更新所需的所有信息
+ * @throws ActionFailureException 如果生成JSON对象失败，抛出此异常
+ */
public JSONObject getUpdateAction(int actionId) {
JSONObject js = new JSONObject();
@@ -135,6 +207,23 @@ public class Task extends Node {
return js;
}
+ /**
+ * 从远程JSON数据解析并设置任务内容。
+ * 业务逻辑：将Google任务服务返回的JSON数据转换为任务对象的属性值。
+ * 解析的JSON字段：
+ *
+ * - id: 任务ID，设置为GID
+ * - last_modified: 最后修改时间戳
+ * - name: 任务名称
+ * - notes: 任务备注
+ * - deleted: 删除状态
+ * - completed: 完成状态
+ *
+ *
+ *
+ * @param js 远程获取的JSON对象，包含Google任务服务返回的任务数据
+ * @throws ActionFailureException 如果解析JSON对象失败，抛出此异常
+ */
public void setContentByRemoteJSON(JSONObject js) {
if (js != null) {
try {
@@ -175,6 +264,18 @@ public class Task extends Node {
}
}
+ /**
+ * 从本地JSON数据解析并设置任务内容。
+ * 业务逻辑：将本地存储的JSON数据转换为任务对象的属性值。
+ * 解析的JSON结构：
+ *
+ * - meta_note: 包含笔记类型信息
+ * - meta_data: 包含笔记内容数组，其中MIME类型为NOTE的数据项的内容被设置为任务名称
+ *
+ *
+ *
+ * @param js 本地存储的JSON对象，包含应用内持久化的任务数据
+ */
public void setContentByLocalJSON(JSONObject js) {
if (js == null || !js.has(GTaskStringUtils.META_HEAD_NOTE)
|| !js.has(GTaskStringUtils.META_HEAD_DATA)) {
@@ -204,6 +305,24 @@ public class Task extends Node {
}
}
+ /**
+ * 从任务内容生成本地JSON对象。
+ * 业务逻辑：根据任务名称和元信息生成本地存储所需的JSON数据结构。
+ * JSON结构说明：
+ *
+ * - meta_note: 包含笔记类型信息
+ * - meta_data: 包含笔记内容数组，其中MIME类型为NOTE的数据项存储任务名称
+ *
+ *
+ * 处理流程：
+ *
+ * - 如果没有元信息，生成新的JSON结构（适用于从Web创建的新任务）
+ * - 如果有元信息，更新现有结构中的任务名称（适用于已同步的任务）
+ *
+ *
+ *
+ * @return 本地存储的JSON对象，包含任务的完整数据结构
+ */
public JSONObject getLocalJSONFromContent() {
String name = getName();
try {
@@ -247,6 +366,19 @@ public class Task extends Node {
}
}
+ /**
+ * 设置任务的元信息。
+ * 业务逻辑：从MetaData对象中解析JSON字符串，获取任务的元信息。
+ * 处理流程：
+ *
+ * - 检查MetaData对象及其notes字段是否为空
+ * - 将notes字段的JSON字符串解析为JSONObject
+ * - 如果解析失败，将元信息设置为null
+ *
+ *
+ *
+ * @param metaData 包含元信息的MetaData对象
+ */
public void setMetaInfo(MetaData metaData) {
if (metaData != null && metaData.getNotes() != null) {
try {
@@ -258,6 +390,30 @@ public class Task extends Node {
}
}
+ /**
+ * 获取同步动作类型。
+ * 业务逻辑：通过比较本地任务和远程任务的状态，确定需要执行的同步动作。
+ * 同步动作类型说明：
+ *
+ * - {@link Node#SYNC_ACTION_NONE}: 无同步动作，本地和远程数据一致
+ * - {@link Node#SYNC_ACTION_UPDATE_LOCAL}: 更新本地数据，应用远程变更
+ * - {@link Node#SYNC_ACTION_UPDATE_REMOTE}: 更新远程数据，应用本地变更
+ * - {@link Node#SYNC_ACTION_UPDATE_CONFLICT}: 同步冲突，本地和远程都有变更
+ * - {@link Node#SYNC_ACTION_ERROR}: 同步错误，数据验证失败
+ *
+ *
+ * 处理流程：
+ *
+ * - 验证元信息和笔记ID的有效性
+ * - 比较本地和远程的最后修改时间
+ * - 检查本地修改标记和GTASK ID的一致性
+ * - 根据比较结果返回相应的同步动作类型
+ *
+ *
+ *
+ * @param c 包含本地任务数据的游标对象
+ * @return 同步动作类型，对应Node类中定义的SYNC_ACTION_*常量
+ */
public int getSyncAction(Cursor c) {
try {
JSONObject noteInfo = null;
@@ -311,39 +467,92 @@ public class Task extends Node {
return SYNC_ACTION_ERROR;
}
+ /**
+ * 判断任务是否值得保存。
+ * 业务逻辑：检查任务是否包含有价值的信息，用于决定是否需要保存到数据库或同步到远程。
+ * 判断条件：满足以下任一条件则认为值得保存：
+ *
+ * - 任务包含元信息（mMetaInfo不为null）
+ * - 任务名称不为空且长度大于0
+ * - 任务备注不为空且长度大于0
+ *
+ *
+ *
+ * @return true表示任务值得保存，false表示任务为空或无价值信息
+ */
public boolean isWorthSaving() {
return mMetaInfo != null || (getName() != null && getName().trim().length() > 0)
|| (getNotes() != null && getNotes().trim().length() > 0);
}
+ /**
+ * 设置任务的完成状态。
+ *
+ * @param completed 任务的完成状态，true表示已完成，false表示未完成
+ */
public void setCompleted(boolean completed) {
this.mCompleted = completed;
}
+ /**
+ * 设置任务的备注信息。
+ *
+ * @param notes 任务的备注信息字符串
+ */
public void setNotes(String notes) {
this.mNotes = notes;
}
+ /**
+ * 设置任务的前一个兄弟任务，用于维护任务的顺序。
+ *
+ * @param priorSibling 前一个兄弟任务对象
+ */
public void setPriorSibling(Task priorSibling) {
this.mPriorSibling = priorSibling;
}
+ /**
+ * 设置任务的父任务列表。
+ *
+ * @param parent 父任务列表对象
+ */
public void setParent(TaskList parent) {
this.mParent = parent;
}
+ /**
+ * 获取任务的完成状态。
+ *
+ * @return 任务的完成状态，true表示已完成，false表示未完成
+ */
public boolean getCompleted() {
return this.mCompleted;
}
+ /**
+ * 获取任务的备注信息。
+ *
+ * @return 任务的备注信息字符串
+ */
public String getNotes() {
return this.mNotes;
}
+ /**
+ * 获取任务的前一个兄弟任务。
+ *
+ * @return 前一个兄弟任务对象，如果没有则返回null
+ */
public Task getPriorSibling() {
return this.mPriorSibling;
}
+ /**
+ * 获取任务的父任务列表。
+ *
+ * @return 父任务列表对象，如果没有则返回null
+ */
public TaskList getParent() {
return this.mParent;
}
diff --git a/src/gtask/data/TaskList.java b/src/gtask/data/TaskList.java
index 4ea21c5..5ff7438 100644
--- a/src/gtask/data/TaskList.java
+++ b/src/gtask/data/TaskList.java
@@ -30,19 +30,53 @@ import org.json.JSONObject;
import java.util.ArrayList;
+/**
+ * Google任务列表的数据模型类，继承自Node类。
+ *
+ * 负责管理任务列表的元数据信息和子任务集合，支持与Google Tasks服务的同步操作。
+ * 主要功能包括：
+ *
+ * - 生成创建/更新任务列表的JSON动作对象
+ * - 从本地/远程JSON数据加载任务列表内容
+ * - 管理子任务集合（添加、删除、移动、查找）
+ * - 确定同步动作类型
+ *
+ *
+ */
public class TaskList extends Node {
private static final String TAG = TaskList.class.getSimpleName();
+ /**
+ * 任务列表在Google任务中的索引位置，用于排序
+ */
private int mIndex;
+ /**
+ * 子任务集合，存储该任务列表下的所有任务对象
+ */
private ArrayList mChildren;
+ /**
+ * 构造函数，初始化任务列表对象
+ *
+ * 创建空的子任务集合，并将索引初始化为1
+ *
+ */
public TaskList() {
super();
mChildren = new ArrayList();
mIndex = 1;
}
+ /**
+ * 生成创建任务列表的JSON动作对象
+ *
+ * 用于向Google Tasks服务发送创建任务列表的请求
+ *
+ * @param actionId 动作ID，用于标识该创建操作
+ * @return 创建任务列表的JSON对象
+ * @throws ActionFailureException 如果生成JSON对象失败
+ */
public JSONObject getCreateAction(int actionId) {
JSONObject js = new JSONObject();
@@ -74,6 +108,15 @@ public class TaskList extends Node {
return js;
}
+ /**
+ * 生成更新任务列表的JSON动作对象
+ *
+ * 用于向Google Tasks服务发送更新任务列表的请求
+ *
+ * @param actionId 动作ID，用于标识该更新操作
+ * @return 更新任务列表的JSON对象
+ * @throws ActionFailureException 如果生成JSON对象失败
+ */
public JSONObject getUpdateAction(int actionId) {
JSONObject js = new JSONObject();
@@ -103,6 +146,14 @@ public class TaskList extends Node {
return js;
}
+ /**
+ * 从远程JSON数据加载任务列表内容
+ *
+ * 将Google Tasks服务返回的JSON数据解析到当前任务列表对象中
+ *
+ * @param js 包含任务列表信息的JSON对象
+ * @throws ActionFailureException 如果解析JSON对象失败
+ */
public void setContentByRemoteJSON(JSONObject js) {
if (js != null) {
try {
@@ -129,6 +180,13 @@ public class TaskList extends Node {
}
}
+ /**
+ * 从本地JSON数据加载任务列表内容
+ *
+ * 将本地数据库中的JSON数据解析到当前任务列表对象中
+ *
+ * @param js 包含本地任务列表信息的JSON对象
+ */
public void setContentByLocalJSON(JSONObject js) {
if (js == null || !js.has(GTaskStringUtils.META_HEAD_NOTE)) {
Log.w(TAG, "setContentByLocalJSON: nothing is avaiable");
@@ -157,6 +215,13 @@ public class TaskList extends Node {
}
}
+ /**
+ * 将任务列表内容转换为本地JSON格式
+ *
+ * 生成用于存储到本地数据库的JSON对象
+ *
+ * @return 包含任务列表本地信息的JSON对象，解析失败时返回null
+ */
public JSONObject getLocalJSONFromContent() {
try {
JSONObject js = new JSONObject();
@@ -183,6 +248,20 @@ public class TaskList extends Node {
}
}
+ /**
+ * 根据本地数据库游标确定同步动作类型
+ *
+ * 比较本地和远程数据的状态，决定执行哪种同步操作
+ *
+ * @param c 本地数据库游标，包含任务列表的本地状态信息
+ * @return 同步动作类型，可能的值：
+ *
+ * - {@link Node#SYNC_ACTION_NONE} - 无需同步
+ * - {@link Node#SYNC_ACTION_UPDATE_LOCAL} - 更新本地数据
+ * - {@link Node#SYNC_ACTION_UPDATE_REMOTE} - 更新远程数据
+ * - {@link Node#SYNC_ACTION_ERROR} - 同步错误
+ *
+ */
public int getSyncAction(Cursor c) {
try {
if (c.getInt(SqlNote.LOCAL_MODIFIED_COLUMN) == 0) {
@@ -216,10 +295,22 @@ public class TaskList extends Node {
return SYNC_ACTION_ERROR;
}
+ /**
+ * 获取子任务数量
+ * @return 子任务集合的大小
+ */
public int getChildTaskCount() {
return mChildren.size();
}
+ /**
+ * 添加子任务到任务列表末尾
+ *
+ * 设置任务的前一个兄弟任务和父任务列表
+ *
+ * @param task 要添加的子任务对象
+ * @return true if the task was added successfully, false otherwise
+ */
public boolean addChildTask(Task task) {
boolean ret = false;
if (task != null && !mChildren.contains(task)) {
@@ -234,6 +325,15 @@ public class TaskList extends Node {
return ret;
}
+ /**
+ * 在指定索引位置添加子任务
+ *
+ * 更新相关任务的前一个兄弟任务引用
+ *
+ * @param task 要添加的子任务对象
+ * @param index 要添加的位置索引
+ * @return true if the task was added successfully, false otherwise
+ */
public boolean addChildTask(Task task, int index) {
if (index < 0 || index > mChildren.size()) {
Log.e(TAG, "add child task: invalid index");
@@ -260,6 +360,14 @@ public class TaskList extends Node {
return true;
}
+ /**
+ * 从任务列表中移除指定的子任务
+ *
+ * 重置被移除任务的前一个兄弟任务和父任务列表引用
+ *
+ * @param task 要移除的子任务对象
+ * @return true if the task was removed successfully, false otherwise
+ */
public boolean removeChildTask(Task task) {
boolean ret = false;
int index = mChildren.indexOf(task);
@@ -281,6 +389,15 @@ public class TaskList extends Node {
return ret;
}
+ /**
+ * 移动子任务到新的索引位置
+ *
+ * 通过先移除后添加的方式实现移动操作
+ *
+ * @param task 要移动的子任务对象
+ * @param index 新的位置索引
+ * @return true if the task was moved successfully, false otherwise
+ */
public boolean moveChildTask(Task task, int index) {
if (index < 0 || index >= mChildren.size()) {
@@ -299,6 +416,11 @@ public class TaskList extends Node {
return (removeChildTask(task) && addChildTask(task, index));
}
+ /**
+ * 根据Google任务ID查找子任务
+ * @param gid Google任务ID
+ * @return 找到的任务对象，未找到时返回null
+ */
public Task findChildTaskByGid(String gid) {
for (int i = 0; i < mChildren.size(); i++) {
Task t = mChildren.get(i);
@@ -309,10 +431,20 @@ public class TaskList extends Node {
return null;
}
+ /**
+ * 获取子任务在列表中的索引位置
+ * @param task 子任务对象
+ * @return 子任务的索引位置，未找到时返回-1
+ */
public int getChildTaskIndex(Task task) {
return mChildren.indexOf(task);
}
+ /**
+ * 根据索引位置获取子任务
+ * @param index 子任务的索引位置
+ * @return 对应的任务对象，索引无效时返回null
+ */
public Task getChildTaskByIndex(int index) {
if (index < 0 || index >= mChildren.size()) {
Log.e(TAG, "getTaskByIndex: invalid index");
@@ -321,6 +453,14 @@ public class TaskList extends Node {
return mChildren.get(index);
}
+ /**
+ * 根据Google任务ID查找子任务
+ *
+ * 与{@link #findChildTaskByGid(String)}功能相同，是该方法的别名
+ *
+ * @param gid Google任务ID
+ * @return 找到的任务对象，未找到时返回null
+ */
public Task getChilTaskByGid(String gid) {
for (Task task : mChildren) {
if (task.getGid().equals(gid))
@@ -329,14 +469,26 @@ public class TaskList extends Node {
return null;
}
+ /**
+ * 获取所有子任务的集合
+ * @return 子任务集合的引用
+ */
public ArrayList getChildTaskList() {
return this.mChildren;
}
+ /**
+ * 设置任务列表的索引位置
+ * @param index 新的索引位置
+ */
public void setIndex(int index) {
this.mIndex = index;
}
+ /**
+ * 获取任务列表的索引位置
+ * @return 当前索引位置
+ */
public int getIndex() {
return this.mIndex;
}
diff --git a/src/gtask/exception/ActionFailureException.java b/src/gtask/exception/ActionFailureException.java
index 15504be..4574dbb 100644
--- a/src/gtask/exception/ActionFailureException.java
+++ b/src/gtask/exception/ActionFailureException.java
@@ -16,17 +16,37 @@
package net.micode.notes.gtask.exception;
+/**
+ * Google任务操作失败异常类。
+ * 设计意图：用于表示Google任务相关操作（如创建、更新、删除等）执行失败的情况。
+ * 核心职责：封装Google任务操作失败的异常信息，提供多种构造方式以适应不同的错误场景。
+ * 关键关联：继承自{@link RuntimeException}，属于非检查型异常，用于表示可恢复的操作失败。
+ */
public class ActionFailureException extends RuntimeException {
private static final long serialVersionUID = 4425249765923293627L;
+ /**
+ * 默认构造方法，创建一个空的操作失败异常。
+ */
public ActionFailureException() {
super();
}
+ /**
+ * 使用指定的错误信息创建操作失败异常。
+ *
+ * @param paramString 错误信息字符串，描述操作失败的原因
+ */
public ActionFailureException(String paramString) {
super(paramString);
}
+ /**
+ * 使用指定的错误信息和根原因创建操作失败异常。
+ *
+ * @param paramString 错误信息字符串，描述操作失败的原因
+ * @param paramThrowable 根原因异常，包含导致操作失败的详细错误信息
+ */
public ActionFailureException(String paramString, Throwable paramThrowable) {
super(paramString, paramThrowable);
}
diff --git a/src/gtask/exception/NetworkFailureException.java b/src/gtask/exception/NetworkFailureException.java
index b08cfb1..05924cf 100644
--- a/src/gtask/exception/NetworkFailureException.java
+++ b/src/gtask/exception/NetworkFailureException.java
@@ -16,17 +16,37 @@
package net.micode.notes.gtask.exception;
+/**
+ * 网络连接失败异常类。
+ * 设计意图：用于表示与Google任务服务通信时网络连接失败的情况。
+ * 核心职责：封装网络连接失败的异常信息，提供多种构造方式以适应不同的错误场景。
+ * 关键关联：继承自{@link Exception}，属于检查型异常，用于表示需要显式处理的网络问题。
+ */
public class NetworkFailureException extends Exception {
private static final long serialVersionUID = 2107610287180234136L;
+ /**
+ * 默认构造方法，创建一个空的网络失败异常。
+ */
public NetworkFailureException() {
super();
}
+ /**
+ * 使用指定的错误信息创建网络失败异常。
+ *
+ * @param paramString 错误信息字符串，描述网络失败的原因
+ */
public NetworkFailureException(String paramString) {
super(paramString);
}
+ /**
+ * 使用指定的错误信息和根原因创建网络失败异常。
+ *
+ * @param paramString 错误信息字符串，描述网络失败的原因
+ * @param paramThrowable 根原因异常，包含导致网络失败的详细错误信息
+ */
public NetworkFailureException(String paramString, Throwable paramThrowable) {
super(paramString, paramThrowable);
}
diff --git a/src/gtask/remote/GTaskASyncTask.java b/src/gtask/remote/GTaskASyncTask.java
index b3b61e7..ed7d6c0 100644
--- a/src/gtask/remote/GTaskASyncTask.java
+++ b/src/gtask/remote/GTaskASyncTask.java
@@ -28,23 +28,68 @@ import net.micode.notes.R;
import net.micode.notes.ui.NotesListActivity;
import net.micode.notes.ui.NotesPreferenceActivity;
-
+/**
+ * Google任务异步同步任务类。
+ * 设计意图：使用AsyncTask实现Google任务的异步同步操作，避免阻塞主线程，并提供用户友好的通知反馈。
+ * 核心职责：
+ *
+ * - 在后台线程执行Google任务的同步操作
+ * - 显示同步进度和结果的通知
+ * - 处理同步完成后的回调
+ * - 支持取消同步操作
+ *
+ * 关键关联：
+ *
+ * - 继承自{@link AsyncTask}，实现异步任务框架
+ * - 使用{@link GTaskManager}执行实际的同步逻辑
+ * - 与{@link GTaskSyncService}配合，支持服务环境下的广播通知
+ * - 通过{@link OnCompleteListener}提供同步完成回调
+ *
+ */
public class GTaskASyncTask extends AsyncTask {
+ /**
+ * Google任务同步通知的唯一ID
+ */
private static int GTASK_SYNC_NOTIFICATION_ID = 5234235;
+ /**
+ * 同步完成监听器接口。
+ * 设计意图：提供Google任务同步完成后的回调机制。
+ */
public interface OnCompleteListener {
+ /**
+ * 同步完成时调用的方法
+ */
void onComplete();
}
+ /**
+ * 上下文对象，用于访问系统服务和资源
+ */
private Context mContext;
+ /**
+ * 通知管理器，用于显示同步进度和结果通知
+ */
private NotificationManager mNotifiManager;
+ /**
+ * Google任务管理器，用于执行实际的同步逻辑
+ */
private GTaskManager mTaskManager;
+ /**
+ * 同步完成监听器，用于处理同步完成后的回调
+ */
private OnCompleteListener mOnCompleteListener;
+ /**
+ * 构造方法，初始化Google任务异步同步任务。
+ *
+ * @param context 上下文对象，用于访问系统服务和资源
+ * @param listener 同步完成监听器，用于处理同步完成后的回调
+ */
public GTaskASyncTask(Context context, OnCompleteListener listener) {
mContext = context;
mOnCompleteListener = listener;
@@ -53,35 +98,81 @@ public class GTaskASyncTask extends AsyncTask {
mTaskManager = GTaskManager.getInstance();
}
+ /**
+ * 取消正在进行的同步操作。
+ */
public void cancelSync() {
mTaskManager.cancelSync();
}
+ /**
+ * 发布同步进度信息。
+ *
+ * @param message 进度信息消息
+ */
public void publishProgess(String message) {
publishProgress(new String[] {
message
});
}
- private void showNotification(int tickerId, String content) {
- Notification notification = new Notification(R.drawable.notification, mContext
- .getString(tickerId), System.currentTimeMillis());
- notification.defaults = Notification.DEFAULT_LIGHTS;
- notification.flags = Notification.FLAG_AUTO_CANCEL;
- PendingIntent pendingIntent;
- if (tickerId != R.string.ticker_success) {
- pendingIntent = PendingIntent.getActivity(mContext, 0, new Intent(mContext,
- NotesPreferenceActivity.class), 0);
-
- } else {
- pendingIntent = PendingIntent.getActivity(mContext, 0, new Intent(mContext,
- NotesListActivity.class), 0);
- }
- notification.setLatestEventInfo(mContext, mContext.getString(R.string.app_name), content,
- pendingIntent);
- mNotifiManager.notify(GTASK_SYNC_NOTIFICATION_ID, notification);
+// private void showNotification(int tickerId, String content) {
+// Notification notification = new Notification(R.drawable.notification, mContext
+// .getString(tickerId), System.currentTimeMillis());
+// notification.defaults = Notification.DEFAULT_LIGHTS;
+// notification.flags = Notification.FLAG_AUTO_CANCEL;
+// PendingIntent pendingIntent;
+// if (tickerId != R.string.ticker_success) {
+// pendingIntent = PendingIntent.getActivity(mContext, 0, new Intent(mContext,
+// NotesPreferenceActivity.class), 0);
+//
+// } else {
+// pendingIntent = PendingIntent.getActivity(mContext, 0, new Intent(mContext,
+// NotesListActivity.class), 0);
+// }
+// notification.setLatestEventInfo(mContext, mContext.getString(R.string.app_name), content,
+// pendingIntent);
+// mNotifiManager.notify(GTASK_SYNC_NOTIFICATION_ID, notification);
+// }
+ /**
+ * 显示同步通知。
+ * 业务逻辑：根据同步状态创建并显示相应的通知，支持成功、失败、取消等不同状态。
+ * 通知点击行为：
+ *
+ * - 成功状态：点击打开笔记列表页面
+ * - 其他状态：点击打开笔记设置页面
+ *
+ *
+ *
+ * @param tickerId 通知标题资源ID
+ * @param content 通知内容字符串
+ */
+private void showNotification(int tickerId, String content) {
+ PendingIntent pendingIntent;
+ if (tickerId != R.string.ticker_success) {
+ pendingIntent = PendingIntent.getActivity(mContext, 0, new Intent(mContext,
+ NotesPreferenceActivity.class), PendingIntent.FLAG_IMMUTABLE);
+ } else {
+ pendingIntent = PendingIntent.getActivity(mContext, 0, new Intent(mContext,
+ NotesListActivity.class), PendingIntent.FLAG_IMMUTABLE);
}
-
+ Notification.Builder builder = new Notification.Builder(mContext)
+ .setAutoCancel(true)
+ .setContentTitle(mContext.getString(R.string.app_name))
+ .setContentText(content)
+ .setContentIntent(pendingIntent)
+ .setWhen(System.currentTimeMillis())
+ .setOngoing(true);
+ Notification notification=builder.getNotification();
+ mNotifiManager.notify(GTASK_SYNC_NOTIFICATION_ID, notification);
+}
+ /**
+ * 在后台线程执行同步操作。
+ * 业务逻辑：初始化同步进度通知，调用GTaskManager执行实际的同步逻辑。
+ *
+ * @param unused 未使用的参数
+ * @return 同步结果状态码，对应GTaskManager中的STATE_*常量
+ */
@Override
protected Integer doInBackground(Void... unused) {
publishProgess(mContext.getString(R.string.sync_progress_login, NotesPreferenceActivity
@@ -89,6 +180,12 @@ public class GTaskASyncTask extends AsyncTask {
return mTaskManager.sync(mContext, this);
}
+ /**
+ * 更新同步进度。
+ * 业务逻辑：显示当前同步进度通知，如果在服务环境下，还会发送广播通知。
+ *
+ * @param progress 进度信息数组，其中第一个元素为进度消息
+ */
@Override
protected void onProgressUpdate(String... progress) {
showNotification(R.string.ticker_syncing, progress[0]);
@@ -97,6 +194,20 @@ public class GTaskASyncTask extends AsyncTask {
}
}
+ /**
+ * 处理同步结果。
+ * 业务逻辑：根据同步结果显示相应的通知，更新最后同步时间，并调用完成监听器。
+ * 同步结果处理：
+ *
+ * - STATE_SUCCESS：显示成功通知，更新最后同步时间
+ * - STATE_NETWORK_ERROR：显示网络错误通知
+ * - STATE_INTERNAL_ERROR：显示内部错误通知
+ * - STATE_SYNC_CANCELLED：显示同步取消通知
+ *
+ *
+ *
+ * @param result 同步结果状态码，对应GTaskManager中的STATE_*常量
+ */
@Override
protected void onPostExecute(Integer result) {
if (result == GTaskManager.STATE_SUCCESS) {
diff --git a/src/gtask/remote/GTaskClient.java b/src/gtask/remote/GTaskClient.java
index c67dfdf..a161ef4 100644
--- a/src/gtask/remote/GTaskClient.java
+++ b/src/gtask/remote/GTaskClient.java
@@ -61,35 +61,108 @@ import java.util.zip.Inflater;
import java.util.zip.InflaterInputStream;
+/**
+ * Google任务API客户端类。
+ * 设计意图：提供与Google任务API交互的核心功能，实现任务的创建、更新、删除等操作。
+ * 核心职责：
+ *
+ * - 处理Google账号的登录认证
+ * - 执行Google任务的CRUD操作
+ * - 管理API请求的Cookie和会话状态
+ * - 处理网络请求和响应，包括压缩数据的解压
+ * - 将本地任务模型转换为Google任务API的JSON格式
+ *
+ * 关键关联：
+ *
+ * - 与{@link GTaskManager}配合，提供任务同步的底层支持
+ * - 使用{@link Task}和{@link TaskList}类封装Google任务数据
+ * - 通过{@link NetworkFailureException}和{@link ActionFailureException}处理异常
+ * - 依赖{@link GTaskStringUtils}提供API交互所需的常量
+ *
+ * 设计特点：
+ *
+ * - 采用单例模式，确保全局只有一个Google任务API客户端实例
+ * - 实现会话管理，避免频繁登录认证
+ * - 支持批量更新操作，提高API调用效率
+ * - 处理不同类型的网络压缩格式（gzip、deflate）
+ *
+ */
public class GTaskClient {
+ /**
+ * 日志标签，用于调试和错误跟踪
+ */
private static final String TAG = GTaskClient.class.getSimpleName();
+ /**
+ * Google任务的基本URL
+ */
private static final String GTASK_URL = "https://mail.google.com/tasks/";
+ /**
+ * Google任务的GET请求URL
+ */
private static final String GTASK_GET_URL = "https://mail.google.com/tasks/ig";
+ /**
+ * Google任务的POST请求URL
+ */
private static final String GTASK_POST_URL = "https://mail.google.com/tasks/r/ig";
+ /**
+ * GTaskClient的单例实例
+ */
private static GTaskClient mInstance = null;
+ /**
+ * HTTP客户端，用于执行与Google任务API的网络请求
+ */
private DefaultHttpClient mHttpClient;
+ /**
+ * 当前使用的GET请求URL
+ */
private String mGetUrl;
+ /**
+ * 当前使用的POST请求URL
+ */
private String mPostUrl;
+ /**
+ * Google任务客户端版本号
+ */
private long mClientVersion;
+ /**
+ * 登录状态标志
+ */
private boolean mLoggedin;
+ /**
+ * 最后一次登录时间
+ */
private long mLastLoginTime;
+ /**
+ * 请求操作ID，用于跟踪API请求
+ */
private int mActionId;
+ /**
+ * 当前登录的Google账号
+ */
private Account mAccount;
+ /**
+ * 批量更新的JSON数组，用于累积多次更新操作
+ */
private JSONArray mUpdateArray;
+ /**
+ * 私有构造方法。
+ * 设计意图：实现单例模式，防止外部直接实例化。
+ * 初始化所有成员变量，设置默认值。
+ */
private GTaskClient() {
mHttpClient = null;
mGetUrl = GTASK_GET_URL;
@@ -102,6 +175,12 @@ public class GTaskClient {
mUpdateArray = null;
}
+ /**
+ * 获取GTaskClient的单例实例。
+ * 业务逻辑：使用双重检查锁定实现线程安全的单例模式。
+ *
+ * @return GTaskClient的单例实例
+ */
public static synchronized GTaskClient getInstance() {
if (mInstance == null) {
mInstance = new GTaskClient();
@@ -109,6 +188,19 @@ public class GTaskClient {
return mInstance;
}
+ /**
+ * 登录Google账号并验证Google任务API。
+ * 业务逻辑：
+ *
+ * - 检查登录状态，如果Cookie过期或账号切换则重新登录
+ * - 获取Google账号的认证令牌
+ * - 如果是自定义域名邮箱，使用自定义URL尝试登录
+ * - 如果自定义域名登录失败，使用官方URL尝试登录
+ *
+ *
+ * @param activity 当前活动的Activity，用于获取账号信息和显示认证界面
+ * @return true表示登录成功，false表示登录失败
+ */
public boolean login(Activity activity) {
// we suppose that the cookie would expire after 5 minutes
// then we need to re-login
@@ -164,6 +256,20 @@ public class GTaskClient {
return true;
}
+ /**
+ * 登录Google账号并获取认证令牌。
+ * 业务逻辑：
+ *
+ * - 获取设备上所有的Google账号
+ * - 根据设置中选择的账号名查找对应的Account对象
+ * - 使用AccountManager获取该账号的认证令牌
+ * - 如果需要，可以使现有令牌失效并重新获取
+ *
+ *
+ * @param activity 当前活动的Activity，用于获取AccountManager
+ * @param invalidateToken 是否使现有令牌失效
+ * @return 认证令牌字符串，如果获取失败则返回null
+ */
private String loginGoogleAccount(Activity activity, boolean invalidateToken) {
String authToken;
AccountManager accountManager = AccountManager.get(activity);
@@ -207,6 +313,19 @@ public class GTaskClient {
return authToken;
}
+ /**
+ * 尝试登录Google任务API。
+ * 业务逻辑：
+ *
+ * - 首先使用提供的认证令牌尝试登录
+ * - 如果登录失败，可能是令牌过期，此时使令牌失效并重新获取
+ * - 使用新的认证令牌再次尝试登录
+ *
+ *
+ * @param activity 当前活动的Activity，用于重新获取认证令牌
+ * @param authToken Google账号的认证令牌
+ * @return true表示登录成功，false表示登录失败
+ */
private boolean tryToLoginGtask(Activity activity, String authToken) {
if (!loginGtask(authToken)) {
// maybe the auth token is out of date, now let's invalidate the
@@ -225,6 +344,20 @@ public class GTaskClient {
return true;
}
+ /**
+ * 登录Google任务API的核心方法。
+ * 业务逻辑：
+ *
+ * - 配置HTTP客户端的连接和套接字超时时间
+ * - 创建Cookie存储以保存认证信息
+ * - 发送HTTP GET请求进行登录认证
+ * - 检查响应中是否包含认证Cookie
+ * - 从响应中解析出客户端版本号
+ *
+ *
+ * @param authToken Google账号的认证令牌
+ * @return true表示登录成功，false表示登录失败
+ */
private boolean loginGtask(String authToken) {
int timeoutConnection = 10000;
int timeoutSocket = 15000;
@@ -280,10 +413,22 @@ public class GTaskClient {
return true;
}
+ /**
+ * 获取操作ID。
+ * 业务逻辑：返回当前操作ID并自增，用于跟踪API请求。
+ *
+ * @return 当前操作ID
+ */
private int getActionId() {
return mActionId++;
}
+ /**
+ * 创建HTTP POST请求。
+ * 业务逻辑：配置POST请求的URL和请求头。
+ *
+ * @return 配置好的HttpPost对象
+ */
private HttpPost createHttpPost() {
HttpPost httpPost = new HttpPost(mPostUrl);
httpPost.setHeader("Content-Type", "application/x-www-form-urlencoded;charset=utf-8");
@@ -291,6 +436,19 @@ public class GTaskClient {
return httpPost;
}
+ /**
+ * 获取HTTP响应内容。
+ * 业务逻辑：
+ *
+ * - 检查响应内容的编码方式
+ * - 如果是gzip或deflate压缩格式，进行解压处理
+ * - 将响应内容转换为字符串
+ *
+ *
+ * @param entity HTTP响应实体
+ * @return 响应内容字符串
+ * @throws IOException 如果读取或解压响应内容时发生错误
+ */
private String getResponseContent(HttpEntity entity) throws IOException {
String contentEncoding = null;
if (entity.getContentEncoding() != null) {
@@ -323,6 +481,21 @@ public class GTaskClient {
}
}
+ /**
+ * 发送POST请求到Google任务API。
+ * 业务逻辑：
+ *
+ * - 检查登录状态，未登录则抛出异常
+ * - 创建并配置HTTP POST请求
+ * - 将JSON数据转换为请求实体
+ * - 发送请求并获取响应
+ * - 将响应内容转换为JSON对象
+ *
+ *
+ * @param js 要发送的JSON对象
+ * @return 响应的JSON对象
+ * @throws NetworkFailureException 如果网络请求失败
+ */
private JSONObject postRequest(JSONObject js) throws NetworkFailureException {
if (!mLoggedin) {
Log.e(TAG, "please login first");
@@ -360,6 +533,19 @@ public class GTaskClient {
}
}
+ /**
+ * 创建新的Google任务。
+ * 业务逻辑：
+ *
+ * - 提交当前累积的更新操作
+ * - 创建任务的JSON表示
+ * - 发送创建任务的POST请求
+ * - 从响应中获取新创建任务的GID并设置到任务对象中
+ *
+ *
+ * @param task 要创建的任务对象
+ * @throws NetworkFailureException 如果网络请求失败
+ */
public void createTask(Task task) throws NetworkFailureException {
commitUpdate();
try {
@@ -386,6 +572,19 @@ public class GTaskClient {
}
}
+ /**
+ * 创建新的Google任务列表。
+ * 业务逻辑：
+ *
+ * - 提交当前累积的更新操作
+ * - 创建任务列表的JSON表示
+ * - 发送创建任务列表的POST请求
+ * - 从响应中获取新创建任务列表的GID并设置到任务列表对象中
+ *
+ *
+ * @param tasklist 要创建的任务列表对象
+ * @throws NetworkFailureException 如果网络请求失败
+ */
public void createTaskList(TaskList tasklist) throws NetworkFailureException {
commitUpdate();
try {
@@ -412,6 +611,12 @@ public class GTaskClient {
}
}
+ /**
+ * 提交累积的更新操作。
+ * 业务逻辑：将累积在mUpdateArray中的所有更新操作发送到Google任务API。
+ *
+ * @throws NetworkFailureException 如果网络请求失败
+ */
public void commitUpdate() throws NetworkFailureException {
if (mUpdateArray != null) {
try {
@@ -433,6 +638,17 @@ public class GTaskClient {
}
}
+ /**
+ * 添加节点更新操作到累积列表。
+ * 业务逻辑：
+ *
+ * - 如果累积的更新操作超过10个，先提交这些更新
+ * - 将节点的更新操作添加到累积列表中
+ *
+ *
+ * @param node 要更新的节点对象
+ * @throws NetworkFailureException 如果网络请求失败（当提交累积更新时）
+ */
public void addUpdateNode(Node node) throws NetworkFailureException {
if (node != null) {
// too many update items may result in an error
@@ -447,6 +663,21 @@ public class GTaskClient {
}
}
+ /**
+ * 移动任务到新的父任务列表或在同一列表中重新排序。
+ * 业务逻辑：
+ *
+ * - 提交当前累积的更新操作
+ * - 创建移动任务的JSON表示
+ * - 如果在同一列表内移动且不是第一个任务，设置前一个兄弟任务的ID
+ * - 发送移动任务的POST请求
+ *
+ *
+ * @param task 要移动的任务
+ * @param preParent 任务的当前父任务列表
+ * @param curParent 任务的新父任务列表
+ * @throws NetworkFailureException 如果网络请求失败
+ */
public void moveTask(Task task, TaskList preParent, TaskList curParent)
throws NetworkFailureException {
commitUpdate();
@@ -486,6 +717,20 @@ public class GTaskClient {
}
}
+ /**
+ * 删除节点。
+ * 业务逻辑：
+ *
+ * - 提交当前累积的更新操作
+ * - 将节点标记为已删除
+ * - 创建删除节点的JSON表示
+ * - 发送删除节点的POST请求
+ * - 清空累积的更新列表
+ *
+ *
+ * @param node 要删除的节点
+ * @throws NetworkFailureException 如果网络请求失败
+ */
public void deleteNode(Node node) throws NetworkFailureException {
commitUpdate();
try {
@@ -509,6 +754,18 @@ public class GTaskClient {
}
}
+ /**
+ * 获取所有的Google任务列表。
+ * 业务逻辑：
+ *
+ * - 检查登录状态
+ * - 发送获取任务列表的GET请求
+ * - 解析响应内容，提取任务列表数据
+ *
+ *
+ * @return 任务列表的JSON数组
+ * @throws NetworkFailureException 如果网络请求失败
+ */
public JSONArray getTaskLists() throws NetworkFailureException {
if (!mLoggedin) {
Log.e(TAG, "please login first");
diff --git a/src/gtask/remote/GTaskManager.java b/src/gtask/remote/GTaskManager.java
index d2b4082..9f76fdd 100644
--- a/src/gtask/remote/GTaskManager.java
+++ b/src/gtask/remote/GTaskManager.java
@@ -48,45 +48,121 @@ import java.util.Iterator;
import java.util.Map;
+/**
+ * Google任务同步管理器类。
+ * 设计意图：作为Google任务与本地便签之间的同步协调中心，管理同步流程和数据转换。
+ * 核心职责：
+ *
+ * - 管理Google任务的登录认证
+ * - 初始化和维护Google任务列表
+ * - 协调本地便签与Google任务之间的内容同步
+ * - 处理同步冲突和异常情况
+ * - 提供同步状态管理和取消机制
+ *
+ * 与其他类的关键关联：
+ *
+ * - 依赖{@link GTaskClient}执行与Google任务API的实际通信
+ * - 使用{@link SqlNote}进行本地便签数据的CRUD操作
+ * - 管理{@link TaskList}和{@link Task}对象的同步状态
+ * - 通过{@link MetaData}存储扩展的任务元数据
+ *
+ */
public class GTaskManager {
private static final String TAG = GTaskManager.class.getSimpleName();
+ /**
+ * 同步状态：成功
+ */
public static final int STATE_SUCCESS = 0;
+ /**
+ * 同步状态：网络错误
+ */
public static final int STATE_NETWORK_ERROR = 1;
+ /**
+ * 同步状态：内部错误
+ */
public static final int STATE_INTERNAL_ERROR = 2;
+ /**
+ * 同步状态：同步进行中
+ */
public static final int STATE_SYNC_IN_PROGRESS = 3;
+ /**
+ * 同步状态：同步已取消
+ */
public static final int STATE_SYNC_CANCELLED = 4;
+ /**
+ * GTaskManager的单例实例
+ */
private static GTaskManager mInstance = null;
+ /**
+ * 用于获取Google认证令牌的Activity上下文
+ */
private Activity mActivity;
+ /**
+ * 应用上下文
+ */
private Context mContext;
+ /**
+ * 内容解析器，用于访问本地便签数据库
+ */
private ContentResolver mContentResolver;
+ /**
+ * 同步状态标志：是否正在同步
+ */
private boolean mSyncing;
+ /**
+ * 同步取消标志：是否已取消同步
+ */
private boolean mCancelled;
+ /**
+ * Google任务列表映射表，key为任务列表的GID
+ */
private HashMap mGTaskListHashMap;
+ /**
+ * Google任务节点映射表，key为节点的GID
+ */
private HashMap mGTaskHashMap;
+ /**
+ * 元数据映射表，key为关联任务的GID
+ */
private HashMap mMetaHashMap;
+ /**
+ * 存储元数据的任务列表
+ */
private TaskList mMetaList;
+ /**
+ * 本地已删除便签的ID集合
+ */
private HashSet mLocalDeleteIdMap;
+ /**
+ * GID到本地ID的映射表
+ */
private HashMap mGidToNid;
+ /**
+ * 本地ID到GID的映射表
+ */
private HashMap mNidToGid;
+ /**
+ * 私有构造函数，初始化同步管理器的内部状态和数据结构。
+ */
private GTaskManager() {
mSyncing = false;
mCancelled = false;
@@ -99,6 +175,11 @@ public class GTaskManager {
mNidToGid = new HashMap();
}
+ /**
+ * 获取GTaskManager的单例实例。
+ *
+ * @return GTaskManager的单例实例
+ */
public static synchronized GTaskManager getInstance() {
if (mInstance == null) {
mInstance = new GTaskManager();
@@ -106,11 +187,41 @@ public class GTaskManager {
return mInstance;
}
+ /**
+ * 设置用于获取Google认证令牌的Activity上下文。
+ *
+ * @param activity 用于获取认证令牌的Activity
+ */
public synchronized void setActivityContext(Activity activity) {
// used for getting authtoken
mActivity = activity;
}
+ /**
+ * 执行Google任务与本地便签的同步操作。
+ *
+ * 业务逻辑：
+ *
+ * - 检查是否已有同步任务在进行中
+ * - 初始化同步上下文和数据结构
+ * - 登录Google任务服务
+ * - 初始化Google任务列表
+ * - 执行内容同步工作
+ * - 处理同步过程中的异常情况
+ * - 清理资源并返回同步结果状态
+ *
+ *
+ * @param context 应用上下文
+ * @param asyncTask 异步任务实例，用于发布同步进度
+ * @return 同步结果状态：
+ *
+ * - {@link #STATE_SUCCESS}：同步成功
+ * - {@link #STATE_NETWORK_ERROR}：网络错误
+ * - {@link #STATE_INTERNAL_ERROR}：内部错误
+ * - {@link #STATE_SYNC_IN_PROGRESS}：已有同步任务在进行中
+ * - {@link #STATE_SYNC_CANCELLED}：同步已取消
+ *
+ */
public int sync(Context context, GTaskASyncTask asyncTask) {
if (mSyncing) {
Log.d(TAG, "Sync is in progress");
@@ -168,6 +279,19 @@ public class GTaskManager {
return mCancelled ? STATE_SYNC_CANCELLED : STATE_SUCCESS;
}
+ /**
+ * 初始化Google任务列表，从Google服务器获取任务列表和任务数据。
+ *
+ * 业务逻辑：
+ *
+ * - 获取所有任务列表
+ * - 初始化元数据列表（如果不存在则创建）
+ * - 加载所有任务列表及其包含的任务
+ * - 将任务列表和任务数据存储到内部映射表中
+ *
+ *
+ * @throws NetworkFailureException 如果网络请求失败
+ */
private void initGTaskList() throws NetworkFailureException {
if (mCancelled)
return;
@@ -247,6 +371,21 @@ public class GTaskManager {
}
}
+ /**
+ * 执行内容同步工作，协调本地便签与Google任务之间的数据同步。
+ *
+ * 业务逻辑：
+ *
+ * - 处理本地已删除的便签
+ * - 优先同步文件夹
+ * - 同步本地存在的便签
+ * - 同步Google服务器上新增的任务
+ * - 清理本地已删除的便签
+ * - 提交更新并刷新本地同步ID
+ *
+ *
+ * @throws NetworkFailureException 如果网络请求失败
+ */
private void syncContent() throws NetworkFailureException {
int syncType;
Cursor c = null;
@@ -351,6 +490,19 @@ public class GTaskManager {
}
+ /**
+ * 同步文件夹（任务列表）数据。
+ *
+ * 业务逻辑：
+ *
+ * - 同步根文件夹
+ * - 同步通话记录文件夹
+ * - 同步本地存在的文件夹
+ * - 同步Google服务器上新增的文件夹
+ *
+ *
+ * @throws NetworkFailureException 如果网络请求失败
+ */
private void syncFolder() throws NetworkFailureException {
Cursor c = null;
String gid;
@@ -476,6 +628,21 @@ public class GTaskManager {
GTaskClient.getInstance().commitUpdate();
}
+ /**
+ * 根据同步类型执行具体的内容同步操作。
+ *
+ * 业务逻辑：
+ *
+ * - 根据同步类型执行不同的同步操作
+ * - 支持添加本地节点、添加远程节点、删除本地节点、删除远程节点、更新本地节点、更新远程节点等操作
+ * - 处理同步冲突情况
+ *
+ *
+ * @param syncType 同步类型
+ * @param node Google任务节点
+ * @param c 本地便签的游标
+ * @throws NetworkFailureException 如果网络请求失败
+ */
private void doContentSync(int syncType, Node node, Cursor c) throws NetworkFailureException {
if (mCancelled) {
return;
@@ -522,6 +689,21 @@ public class GTaskManager {
}
}
+ /**
+ * 将Google任务节点添加到本地便签数据库。
+ *
+ * 业务逻辑：
+ *
+ * - 根据节点类型创建对应的SqlNote对象
+ * - 处理JSON数据中的ID冲突
+ * - 设置节点的父ID
+ * - 创建本地节点并更新映射表
+ * - 更新元数据
+ *
+ *
+ * @param node 要添加的Google任务节点
+ * @throws NetworkFailureException 如果网络请求失败
+ */
private void addLocalNode(Node node) throws NetworkFailureException {
if (mCancelled) {
return;
@@ -596,6 +778,21 @@ public class GTaskManager {
updateRemoteMeta(node.getGid(), sqlNote);
}
+ /**
+ * 更新本地便签数据库中的节点数据。
+ *
+ * 业务逻辑：
+ *
+ * - 创建SqlNote对象并更新内容
+ * - 设置节点的父ID
+ * - 提交更新并更新映射表
+ * - 更新元数据
+ *
+ *
+ * @param node 要更新的Google任务节点
+ * @param c 本地便签的游标
+ * @throws NetworkFailureException 如果网络请求失败
+ */
private void updateLocalNode(Node node, Cursor c) throws NetworkFailureException {
if (mCancelled) {
return;
@@ -619,6 +816,21 @@ public class GTaskManager {
updateRemoteMeta(node.getGid(), sqlNote);
}
+ /**
+ * 将本地便签添加到Google服务器。
+ *
+ * 业务逻辑：
+ *
+ * - 根据本地便签类型创建对应的Google任务或任务列表
+ * - 处理已存在的文件夹
+ * - 创建远程节点并更新本地便签的GID
+ * - 更新映射表
+ *
+ *
+ * @param node Google任务节点
+ * @param c 本地便签的游标
+ * @throws NetworkFailureException 如果网络请求失败
+ */
private void addRemoteNode(Node node, Cursor c) throws NetworkFailureException {
if (mCancelled) {
return;
@@ -692,6 +904,21 @@ public class GTaskManager {
mNidToGid.put(sqlNote.getId(), n.getGid());
}
+ /**
+ * 更新Google服务器上的节点数据。
+ *
+ * 业务逻辑：
+ *
+ * - 更新远程节点的内容
+ * - 更新元数据
+ * - 处理任务移动情况
+ * - 清除本地修改标志
+ *
+ *
+ * @param node 要更新的Google任务节点
+ * @param c 本地便签的游标
+ * @throws NetworkFailureException 如果网络请求失败
+ */
private void updateRemoteNode(Node node, Cursor c) throws NetworkFailureException {
if (mCancelled) {
return;
@@ -730,6 +957,19 @@ public class GTaskManager {
sqlNote.commit(true);
}
+ /**
+ * 更新远程服务器上的元数据。
+ *
+ * 业务逻辑：
+ *
+ * - 检查元数据是否已存在
+ * - 如果已存在则更新，否则创建新的元数据
+ *
+ *
+ * @param gid 任务的GID
+ * @param sqlNote 本地便签对象
+ * @throws NetworkFailureException 如果网络请求失败
+ */
private void updateRemoteMeta(String gid, SqlNote sqlNote) throws NetworkFailureException {
if (sqlNote != null && sqlNote.isNoteType()) {
MetaData metaData = mMetaHashMap.get(gid);
@@ -746,6 +986,17 @@ public class GTaskManager {
}
}
+ /**
+ * 刷新本地便签的同步ID。
+ *
+ * 业务逻辑：
+ *
+ * - 重新初始化Google任务列表
+ * - 更新本地便签的同步ID
+ *
+ *
+ * @throws NetworkFailureException 如果网络请求失败
+ */
private void refreshLocalSyncId() throws NetworkFailureException {
if (mCancelled) {
return;
@@ -790,10 +1041,18 @@ public class GTaskManager {
}
}
+ /**
+ * 获取当前同步账户的名称。
+ *
+ * @return 当前同步账户的名称
+ */
public String getSyncAccount() {
return GTaskClient.getInstance().getSyncAccount().name;
}
+ /**
+ * 取消正在进行的同步操作。
+ */
public void cancelSync() {
mCancelled = true;
}
diff --git a/src/gtask/remote/GTaskSyncService.java b/src/gtask/remote/GTaskSyncService.java
index cca36f7..9b215a9 100644
--- a/src/gtask/remote/GTaskSyncService.java
+++ b/src/gtask/remote/GTaskSyncService.java
@@ -23,25 +23,81 @@ import android.content.Intent;
import android.os.Bundle;
import android.os.IBinder;
+/**
+ * Google任务同步服务类。
+ * 设计意图：作为Android服务组件，管理Google任务的同步操作，提供同步的启动和取消功能。
+ * 核心职责：
+ *
+ * - 接收同步操作的启动和取消指令
+ * - 管理异步同步任务的生命周期
+ * - 通过广播通知同步状态和进度
+ * - 处理低内存情况
+ *
+ * 与其他类的关键关联：
+ *
+ * - 使用{@link GTaskASyncTask}执行实际的同步操作
+ * - 依赖{@link GTaskManager}进行同步逻辑处理
+ * - 通过广播与UI组件通信
+ *
+ */
public class GTaskSyncService extends Service {
+ /**
+ * 操作类型的Intent extra键名
+ */
public final static String ACTION_STRING_NAME = "sync_action_type";
+ /**
+ * 启动同步操作的动作类型
+ */
public final static int ACTION_START_SYNC = 0;
+ /**
+ * 取消同步操作的动作类型
+ */
public final static int ACTION_CANCEL_SYNC = 1;
+ /**
+ * 无效的动作类型
+ */
public final static int ACTION_INVALID = 2;
+ /**
+ * 同步服务广播的名称
+ */
public final static String GTASK_SERVICE_BROADCAST_NAME = "net.micode.notes.gtask.remote.gtask_sync_service";
+ /**
+ * 广播中表示是否正在同步的extra键名
+ */
public final static String GTASK_SERVICE_BROADCAST_IS_SYNCING = "isSyncing";
+ /**
+ * 广播中表示同步进度消息的extra键名
+ */
public final static String GTASK_SERVICE_BROADCAST_PROGRESS_MSG = "progressMsg";
+ /**
+ * 当前正在执行的同步任务实例
+ */
private static GTaskASyncTask mSyncTask = null;
+ /**
+ * 当前同步进度消息
+ */
private static String mSyncProgress = "";
+ /**
+ * 启动Google任务同步操作。
+ *
+ * 业务逻辑：
+ *
+ * - 检查是否已有同步任务在执行
+ * - 如果没有，则创建新的异步同步任务
+ * - 设置任务完成监听器
+ * - 发送同步开始的广播
+ * - 执行异步同步任务
+ *
+ */
private void startSync() {
if (mSyncTask == null) {
mSyncTask = new GTaskASyncTask(this, new GTaskASyncTask.OnCompleteListener() {
@@ -56,17 +112,49 @@ public class GTaskSyncService extends Service {
}
}
+ /**
+ * 取消正在执行的Google任务同步操作。
+ *
+ * 业务逻辑：
+ *
+ * - 检查是否有同步任务在执行
+ * - 如果有，则调用任务的取消方法
+ *
+ */
private void cancelSync() {
if (mSyncTask != null) {
mSyncTask.cancelSync();
}
}
+ /**
+ * 创建服务时的回调方法。
+ *
+ * 业务逻辑：
+ *
+ */
@Override
public void onCreate() {
mSyncTask = null;
}
+ /**
+ * 服务启动时的回调方法，处理启动服务的Intent。
+ *
+ * 业务逻辑：
+ *
+ * - 解析Intent中的操作类型
+ * - 根据操作类型执行相应的同步操作（启动或取消）
+ * - 返回START_STICKY表示服务被系统终止后会尝试重新启动
+ *
+ *
+ * @param intent 启动服务的Intent
+ * @param flags 启动标志
+ * @param startId 启动ID
+ * @return 服务的启动模式
+ */
@Override
public int onStartCommand(Intent intent, int flags, int startId) {
Bundle bundle = intent.getExtras();
@@ -86,6 +174,14 @@ public class GTaskSyncService extends Service {
return super.onStartCommand(intent, flags, startId);
}
+ /**
+ * 系统内存不足时的回调方法。
+ *
+ * 业务逻辑：
+ *
+ * - 在内存不足的情况下，取消正在执行的同步任务以释放资源
+ *
+ */
@Override
public void onLowMemory() {
if (mSyncTask != null) {
@@ -93,10 +189,33 @@ public class GTaskSyncService extends Service {
}
}
+ /**
+ * 绑定服务时的回调方法。
+ *
+ * 业务逻辑：
+ *
+ *
+ * @param intent 绑定服务的Intent
+ * @return 绑定接口，此处返回null
+ */
public IBinder onBind(Intent intent) {
return null;
}
+ /**
+ * 发送同步状态的广播。
+ *
+ * 业务逻辑：
+ *
+ * - 更新同步进度消息
+ * - 创建广播Intent并设置同步状态和进度信息
+ * - 发送广播通知UI组件同步状态的变化
+ *
+ *
+ * @param msg 同步进度消息
+ */
public void sendBroadcast(String msg) {
mSyncProgress = msg;
Intent intent = new Intent(GTASK_SERVICE_BROADCAST_NAME);
@@ -105,6 +224,18 @@ public class GTaskSyncService extends Service {
sendBroadcast(intent);
}
+ /**
+ * 静态方法：启动Google任务同步服务。
+ *
+ * 业务逻辑：
+ *
+ * - 设置GTaskManager的Activity上下文
+ * - 创建启动服务的Intent并设置操作类型
+ * - 启动同步服务
+ *
+ *
+ * @param activity 调用该方法的Activity实例
+ */
public static void startSync(Activity activity) {
GTaskManager.getInstance().setActivityContext(activity);
Intent intent = new Intent(activity, GTaskSyncService.class);
@@ -112,16 +243,47 @@ public class GTaskSyncService extends Service {
activity.startService(intent);
}
+ /**
+ * 静态方法：取消Google任务同步服务。
+ *
+ * 业务逻辑：
+ *
+ * - 创建启动服务的Intent并设置取消操作类型
+ * - 启动同步服务以执行取消操作
+ *
+ *
+ * @param context 调用该方法的上下文
+ */
public static void cancelSync(Context context) {
Intent intent = new Intent(context, GTaskSyncService.class);
intent.putExtra(GTaskSyncService.ACTION_STRING_NAME, GTaskSyncService.ACTION_CANCEL_SYNC);
context.startService(intent);
}
+ /**
+ * 静态方法：检查是否正在进行同步操作。
+ *
+ * 业务逻辑：
+ *
+ * - 通过检查同步任务引用是否为null来判断同步状态
+ *
+ *
+ * @return true表示正在同步，false表示没有同步操作进行
+ */
public static boolean isSyncing() {
return mSyncTask != null;
}
+ /**
+ * 静态方法：获取当前同步进度消息。
+ *
+ * 业务逻辑：
+ *
+ *
+ * @return 当前同步进度消息
+ */
public static String getProgressString() {
return mSyncProgress;
}
diff --git a/src/model/Note.java b/src/model/Note.java
index 6706cf6..b4f190f 100644
--- a/src/model/Note.java
+++ b/src/model/Note.java
@@ -34,12 +34,61 @@ import net.micode.notes.data.Notes.TextNote;
import java.util.ArrayList;
+/**
+ * 核心笔记数据模型类，负责管理笔记的基本信息和数据变更。
+ * 设计意图：将笔记的元数据变更和具体内容数据分离管理，提高数据操作的灵活性和效率。
+ *
+ * - 通过{@link #mNoteDiffValues}跟踪笔记元数据的变更
+ * - 通过内部类{@link NoteData}管理笔记的具体内容数据（文本、通话记录等）
+ * - 提供与ContentResolver的交互接口，实现数据持久化和同步
+ *
+ * 关键关联：
+ *
+ * - 与{@link net.micode.notes.data.NotesProvider}交互，实现数据的CRUD操作
+ * - 使用{@link android.content.ContentValues}存储数据变更
+ * - 通过{@link android.content.ContentProviderOperation}执行批量数据更新
+ *
+ */
public class Note {
+ /**
+ * 存储笔记元数据的变更记录。
+ * 业务含义：记录笔记的基本信息变更，如标题、创建时间、修改时间等。
+ * 约束条件：仅包含需要更新到数据库的字段变更，不包含笔记的具体内容数据。
+ */
private ContentValues mNoteDiffValues;
+
+ /**
+ * 管理笔记的具体内容数据。
+ * 业务含义：处理笔记的文本内容、通话记录等具体数据的存储和变更。
+ */
private NoteData mNoteData;
+
+ /**
+ * 日志标签。
+ * 业务含义：用于在日志中标识Note类的相关操作。
+ */
private static final String TAG = "Note";
/**
- * Create a new note id for adding a new note to databases
+ * 生成新的笔记ID，用于向数据库添加新笔记。
+ * 业务逻辑：在数据库中创建一条新的笔记记录，返回其生成的ID。
+ * 线程安全：方法使用synchronized关键字确保在多线程环境下的安全性。
+ *
+ * @param context 上下文对象，用于获取ContentResolver
+ * @param folderId 文件夹ID，新笔记将被添加到该文件夹下
+ * @return 生成的新笔记ID
+ * @throws IllegalStateException 当生成的笔记ID为-1时抛出
+ *
+ * 跨类调用：
+ *
+ * - 通过{@link Context#getContentResolver()}获取ContentResolver
+ * - 调用{@link android.content.ContentResolver#insert(Uri, ContentValues)}向{@link Notes#CONTENT_NOTE_URI}插入新笔记
+ *
+ *
+ * 错误处理：
+ *
+ * - 捕获NumberFormatException异常，记录日志并返回0
+ * - 当生成的笔记ID为-1时，抛出IllegalStateException异常
+ *
*/
public static synchronized long getNewNoteId(Context context, long folderId) {
// Create a new note in the database
@@ -65,41 +114,143 @@ public class Note {
return noteId;
}
+ /**
+ * Note类的默认构造函数。
+ * 功能：初始化笔记的元数据变更记录和内容数据管理对象。
+ *
+ * - 初始化{@link #mNoteDiffValues}为新的ContentValues对象，用于跟踪元数据变更
+ * - 初始化{@link #mNoteData}为新的NoteData对象，用于管理具体内容数据
+ *
+ */
public Note() {
mNoteDiffValues = new ContentValues();
mNoteData = new NoteData();
}
+ /**
+ * 设置笔记的元数据字段值。
+ * 业务逻辑：更新笔记的元数据变更记录，并标记为本地已修改。
+ *
+ * @param key 元数据字段名
+ * @param value 元数据字段值
+ *
+ * 自动更新的字段：
+ *
+ * - {@link NoteColumns#LOCAL_MODIFIED}：标记为1（已修改）
+ * - {@link NoteColumns#MODIFIED_DATE}：更新为当前时间戳
+ *
+ */
public void setNoteValue(String key, String value) {
mNoteDiffValues.put(key, value);
mNoteDiffValues.put(NoteColumns.LOCAL_MODIFIED, 1);
mNoteDiffValues.put(NoteColumns.MODIFIED_DATE, System.currentTimeMillis());
}
+ /**
+ * 设置笔记的文本数据字段值。
+ * 业务逻辑：通过{@link NoteData}对象更新笔记的文本内容数据。
+ *
+ * @param key 文本数据字段名
+ * @param value 文本数据字段值
+ */
public void setTextData(String key, String value) {
mNoteData.setTextData(key, value);
}
+ /**
+ * 设置笔记文本数据的ID。
+ * 业务逻辑：通过{@link NoteData}对象设置文本数据的ID。
+ *
+ * @param id 文本数据ID
+ */
public void setTextDataId(long id) {
mNoteData.setTextDataId(id);
}
+ /**
+ * 获取笔记文本数据的ID。
+ * 业务逻辑：通过{@link NoteData}对象获取文本数据的ID。
+ *
+ * @return 文本数据ID
+ */
public long getTextDataId() {
return mNoteData.mTextDataId;
}
+ /**
+ * 设置笔记通话数据的ID。
+ * 业务逻辑：通过{@link NoteData}对象设置通话数据的ID。
+ *
+ * @param id 通话数据ID
+ */
public void setCallDataId(long id) {
mNoteData.setCallDataId(id);
}
+ /**
+ * 设置笔记的通话数据字段值。
+ * 业务逻辑：通过{@link NoteData}对象更新笔记的通话记录数据。
+ *
+ * @param key 通话数据字段名
+ * @param value 通话数据字段值
+ */
public void setCallData(String key, String value) {
mNoteData.setCallData(key, value);
}
+ /**
+ * 检查笔记是否在本地已修改。
+ * 业务逻辑：判断笔记的元数据或内容数据是否发生了变更。
+ *
+ * @return true表示笔记已修改，false表示未修改
+ *
+ * 判断条件：
+ *
+ * - 元数据变更：{@link #mNoteDiffValues}的大小大于0
+ * - 内容数据变更：通过{@link NoteData#isLocalModified()}判断
+ *
+ */
public boolean isLocalModified() {
return mNoteDiffValues.size() > 0 || mNoteData.isLocalModified();
}
+ /**
+ * 将笔记的变更同步到ContentResolver。
+ * 业务逻辑：将笔记的元数据变更和内容数据变更持久化到数据库。
+ *
+ * @param context 上下文对象，用于获取ContentResolver
+ * @param noteId 笔记ID，指定要同步的笔记
+ * @return true表示同步成功，false表示同步失败
+ * @throws IllegalArgumentException 当noteId无效（<=0）时抛出
+ *
+ * 同步流程：
+ *
+ * - 检查noteId是否有效
+ * - 检查笔记是否已修改，未修改则直接返回true
+ * - 更新笔记的元数据变更到ContentResolver
+ * - 如果内容数据已修改，将其同步到ContentResolver
+ * - 返回同步结果
+ *
+ *
+ * 数据流转换：
+ *
+ * - 元数据变更：从{@link #mNoteDiffValues}转换为ContentResolver.update()的参数
+ * - 内容数据变更：通过{@link NoteData#pushIntoContentResolver(Context, long)}方法处理
+ *
+ *
+ * 错误处理：
+ *
+ * - 元数据更新失败：记录日志，但继续执行内容数据同步（为了数据安全性）
+ * - 内容数据同步失败：返回false表示同步失败
+ *
+ *
+ * 跨类调用：
+ *
+ * - 通过{@link Context#getContentResolver()}获取ContentResolver
+ * - 调用{@link android.content.ContentResolver#update(Uri, ContentValues, String, String[])}更新元数据
+ * - 调用{@link NoteData#pushIntoContentResolver(Context, long)}同步内容数据
+ *
+ */
public boolean syncNote(Context context, long noteId) {
if (noteId <= 0) {
throw new IllegalArgumentException("Wrong note id:" + noteId);
@@ -130,17 +281,65 @@ public class Note {
return true;
}
+ /**
+ * 笔记内容数据管理类，处理笔记的具体内容存储和变更。
+ * 设计意图：将笔记的内容数据与元数据分离管理，提高数据操作的灵活性和效率。
+ * 作为{@link Note}类的内部类，专门负责处理：
+ *
+ * - 笔记的文本内容数据
+ * - 笔记的通话记录数据
+ * - 内容数据的变更跟踪
+ * - 内容数据与ContentResolver的同步
+ *
+ * 关键关联：
+ *
+ * - 与{@link Note}类紧密协作，共享笔记元数据变更的跟踪
+ * - 使用{@link ContentValues}存储内容数据的变更
+ * - 通过{@link ContentProviderOperation}执行批量数据更新
+ *
+ */
private class NoteData {
+ /**
+ * 文本数据的ID。
+ * 业务含义：唯一标识笔记的文本内容数据记录。
+ * 约束条件：0表示文本数据尚未保存到数据库。
+ */
private long mTextDataId;
+ /**
+ * 存储文本数据的变更记录。
+ * 业务含义：记录笔记文本内容的变更，如正文、标题等。
+ */
private ContentValues mTextDataValues;
+ /**
+ * 通话数据的ID。
+ * 业务含义：唯一标识笔记的通话记录数据记录。
+ * 约束条件：0表示通话数据尚未保存到数据库。
+ */
private long mCallDataId;
+ /**
+ * 存储通话数据的变更记录。
+ * 业务含义：记录笔记通话记录的变更，如通话号码、通话时间等。
+ */
private ContentValues mCallDataValues;
+ /**
+ * 日志标签。
+ * 业务含义：用于在日志中标识NoteData类的相关操作。
+ */
private static final String TAG = "NoteData";
+ /**
+ * NoteData类的默认构造函数。
+ * 功能：初始化笔记内容数据的变更记录和ID。
+ *
+ * - 初始化{@link #mTextDataValues}为新的ContentValues对象
+ * - 初始化{@link #mCallDataValues}为新的ContentValues对象
+ * - 将{@link #mTextDataId}和{@link #mCallDataId}初始化为0
+ *
+ */
public NoteData() {
mTextDataValues = new ContentValues();
mCallDataValues = new ContentValues();
@@ -148,10 +347,29 @@ public class Note {
mCallDataId = 0;
}
+ /**
+ * 检查内容数据是否在本地已修改。
+ * 业务逻辑：判断文本数据或通话数据是否发生了变更。
+ *
+ * @return true表示内容数据已修改，false表示未修改
+ *
+ * 判断条件：
+ *
+ * - 文本数据变更：{@link #mTextDataValues}的大小大于0
+ * - 通话数据变更：{@link #mCallDataValues}的大小大于0
+ *
+ */
boolean isLocalModified() {
return mTextDataValues.size() > 0 || mCallDataValues.size() > 0;
}
+ /**
+ * 设置文本数据的ID。
+ * 业务逻辑：更新文本数据的唯一标识符。
+ *
+ * @param id 文本数据ID
+ * @throws IllegalArgumentException 当id无效（<=0）时抛出
+ */
void setTextDataId(long id) {
if(id <= 0) {
throw new IllegalArgumentException("Text data id should larger than 0");
@@ -159,6 +377,13 @@ public class Note {
mTextDataId = id;
}
+ /**
+ * 设置通话数据的ID。
+ * 业务逻辑：更新通话数据的唯一标识符。
+ *
+ * @param id 通话数据ID
+ * @throws IllegalArgumentException 当id无效（<=0）时抛出
+ */
void setCallDataId(long id) {
if (id <= 0) {
throw new IllegalArgumentException("Call data id should larger than 0");
@@ -166,18 +391,82 @@ public class Note {
mCallDataId = id;
}
+ /**
+ * 设置通话数据的字段值。
+ * 业务逻辑：更新通话数据的变更记录，并标记笔记为本地已修改。
+ *
+ * @param key 通话数据字段名
+ * @param value 通话数据字段值
+ *
+ * 自动更新的字段：
+ *
+ * - 通过外部类{@link Note}的{@link Note#mNoteDiffValues}更新{@link NoteColumns#LOCAL_MODIFIED}为1
+ * - 通过外部类{@link Note}的{@link Note#mNoteDiffValues}更新{@link NoteColumns#MODIFIED_DATE}为当前时间戳
+ *
+ */
void setCallData(String key, String value) {
mCallDataValues.put(key, value);
mNoteDiffValues.put(NoteColumns.LOCAL_MODIFIED, 1);
mNoteDiffValues.put(NoteColumns.MODIFIED_DATE, System.currentTimeMillis());
}
+ /**
+ * 设置文本数据的字段值。
+ * 业务逻辑：更新文本数据的变更记录，并标记笔记为本地已修改。
+ *
+ * @param key 文本数据字段名
+ * @param value 文本数据字段值
+ *
+ * 自动更新的字段：
+ *
+ * - 通过外部类{@link Note}的{@link Note#mNoteDiffValues}更新{@link NoteColumns#LOCAL_MODIFIED}为1
+ * - 通过外部类{@link Note}的{@link Note#mNoteDiffValues}更新{@link NoteColumns#MODIFIED_DATE}为当前时间戳
+ *
+ */
void setTextData(String key, String value) {
mTextDataValues.put(key, value);
mNoteDiffValues.put(NoteColumns.LOCAL_MODIFIED, 1);
mNoteDiffValues.put(NoteColumns.MODIFIED_DATE, System.currentTimeMillis());
}
+ /**
+ * 将内容数据的变更同步到ContentResolver。
+ * 业务逻辑：处理文本数据和通话数据的插入或更新操作。
+ *
+ * @param context 上下文对象，用于获取ContentResolver
+ * @param noteId 笔记ID，指定内容数据所属的笔记
+ * @return 成功时返回笔记的Uri，失败时返回null
+ * @throws IllegalArgumentException 当noteId无效（<=0）时抛出
+ *
+ * 同步流程：
+ *
+ * - 检查noteId是否有效
+ * - 处理文本数据：
+ *
+ * - 如果{@link #mTextDataId}为0，执行插入操作
+ * - 否则，执行更新操作
+ *
+ * - 处理通话数据：
+ *
+ * - 如果{@link #mCallDataId}为0，执行插入操作
+ * - 否则，执行更新操作
+ *
+ * - 通过ContentProviderOperation批量执行所有操作
+ *
+ *
+ * 跨类调用：
+ *
+ * - 通过{@link Context#getContentResolver()}获取ContentResolver
+ * - 调用{@link android.content.ContentResolver#insert(Uri, ContentValues)}插入新数据
+ * - 调用{@link android.content.ContentResolver#applyBatch(String, ArrayList)}执行批量操作
+ *
+ *
+ * 错误处理：
+ *
+ * - 插入文本数据失败：记录日志并返回null
+ * - 批量操作失败：捕获RemoteException和OperationApplicationException，记录日志并返回null
+ *
+ */
Uri pushIntoContentResolver(Context context, long noteId) {
/**
* Check for safety
diff --git a/src/model/WorkingNote.java b/src/model/WorkingNote.java
index be081e4..e142def 100644
--- a/src/model/WorkingNote.java
+++ b/src/model/WorkingNote.java
@@ -32,36 +32,116 @@ import net.micode.notes.data.Notes.TextNote;
import net.micode.notes.tool.ResourceParser.NoteBgResources;
+/**
+ * 工作笔记管理类，负责处理笔记的编辑、保存、加载等操作。
+ * 设计意图：作为Note类的包装类，提供更便捷的笔记操作接口，处理用户交互和数据同步。
+ *
+ * - 管理笔记的元数据和内容数据
+ * - 提供笔记的加载、保存、删除等功能
+ * - 处理笔记的设置变更（如背景颜色、提醒时间、清单模式）
+ * - 支持小组件交互和通知
+ *
+ * 关键关联：
+ *
+ * - 与{@link Note}类紧密协作，管理笔记的核心数据
+ * - 通过{@link Context}与系统服务交互
+ * - 使用{@link NotesProvider}进行数据持久化
+ * - 通过{@link NoteSettingChangedListener}接口回调设置变更事件
+ *
+ */
public class WorkingNote {
- // Note for the working note
+ /**
+ * 笔记的核心数据管理对象。
+ * 业务含义：封装笔记的元数据和内容数据的变更管理。
+ */
private Note mNote;
- // Note Id
+
+ /**
+ * 笔记的唯一标识符。
+ * 业务含义：在数据库中唯一标识一条笔记记录。
+ * 约束条件：0表示笔记尚未保存到数据库。
+ */
private long mNoteId;
- // Note content
+
+ /**
+ * 笔记的内容文本。
+ * 业务含义：笔记的主要内容数据。
+ */
private String mContent;
- // Note mode
+
+ /**
+ * 笔记的模式。
+ * 业务含义：表示笔记的显示模式，如普通文本模式或清单模式。
+ */
private int mMode;
+ /**
+ * 笔记的提醒时间。
+ * 业务含义：笔记的闹钟提醒时间戳。
+ * 约束条件：0表示无提醒。
+ */
private long mAlertDate;
+ /**
+ * 笔记的最后修改时间。
+ * 业务含义：记录笔记最后一次修改的时间戳。
+ */
private long mModifiedDate;
+ /**
+ * 笔记的背景颜色ID。
+ * 业务含义：标识笔记使用的背景颜色资源。
+ */
private int mBgColorId;
+ /**
+ * 笔记关联的小组件ID。
+ * 业务含义：与笔记关联的桌面小组件的唯一标识符。
+ * 约束条件：{@link AppWidgetManager#INVALID_APPWIDGET_ID}表示无关联小组件。
+ */
private int mWidgetId;
+ /**
+ * 笔记关联的小组件类型。
+ * 业务含义：标识与笔记关联的桌面小组件的类型。
+ * 约束条件：{@link Notes#TYPE_WIDGET_INVALIDE}表示无关联小组件。
+ */
private int mWidgetType;
+ /**
+ * 笔记所在的文件夹ID。
+ * 业务含义：标识笔记所属的文件夹。
+ */
private long mFolderId;
+ /**
+ * 上下文对象。
+ * 业务含义：用于访问系统服务和资源。
+ */
private Context mContext;
+ /**
+ * 日志标签。
+ * 业务含义：用于在日志中标识WorkingNote类的相关操作。
+ */
private static final String TAG = "WorkingNote";
+ /**
+ * 笔记是否已删除的标记。
+ * 业务含义：标识笔记是否已被标记为删除。
+ */
private boolean mIsDeleted;
+ /**
+ * 笔记设置变更监听器。
+ * 业务含义：用于监听笔记设置的变更事件。
+ */
private NoteSettingChangedListener mNoteSettingStatusListener;
+ /**
+ * 笔记内容数据的查询投影。
+ * 业务含义：定义从Notes.CONTENT_DATA_URI查询时需要获取的列。
+ */
public static final String[] DATA_PROJECTION = new String[] {
DataColumns.ID,
DataColumns.CONTENT,
@@ -72,6 +152,10 @@ public class WorkingNote {
DataColumns.DATA4,
};
+ /**
+ * 笔记元数据的查询投影。
+ * 业务含义：定义从Notes.CONTENT_NOTE_URI查询时需要获取的列。
+ */
public static final String[] NOTE_PROJECTION = new String[] {
NoteColumns.PARENT_ID,
NoteColumns.ALERTED_DATE,
@@ -81,27 +165,73 @@ public class WorkingNote {
NoteColumns.MODIFIED_DATE
};
+ /**
+ * DATA_PROJECTION中ID列的索引。
+ */
private static final int DATA_ID_COLUMN = 0;
+ /**
+ * DATA_PROJECTION中CONTENT列的索引。
+ */
private static final int DATA_CONTENT_COLUMN = 1;
+ /**
+ * DATA_PROJECTION中MIME_TYPE列的索引。
+ */
private static final int DATA_MIME_TYPE_COLUMN = 2;
+ /**
+ * DATA_PROJECTION中DATA1列的索引，用于存储模式信息。
+ */
private static final int DATA_MODE_COLUMN = 3;
+ /**
+ * NOTE_PROJECTION中PARENT_ID列的索引。
+ */
private static final int NOTE_PARENT_ID_COLUMN = 0;
+ /**
+ * NOTE_PROJECTION中ALERTED_DATE列的索引。
+ */
private static final int NOTE_ALERTED_DATE_COLUMN = 1;
+ /**
+ * NOTE_PROJECTION中BG_COLOR_ID列的索引。
+ */
private static final int NOTE_BG_COLOR_ID_COLUMN = 2;
+ /**
+ * NOTE_PROJECTION中WIDGET_ID列的索引。
+ */
private static final int NOTE_WIDGET_ID_COLUMN = 3;
+ /**
+ * NOTE_PROJECTION中WIDGET_TYPE列的索引。
+ */
private static final int NOTE_WIDGET_TYPE_COLUMN = 4;
+ /**
+ * NOTE_PROJECTION中MODIFIED_DATE列的索引。
+ */
private static final int NOTE_MODIFIED_DATE_COLUMN = 5;
- // New note construct
+ /**
+ * 创建新笔记的构造函数。
+ * 功能：初始化一个新的工作笔记对象，设置默认值。
+ *
+ * @param context 上下文对象，用于访问系统服务
+ * @param folderId 文件夹ID，新笔记将被添加到该文件夹
+ *
+ * 默认初始化：
+ *
+ * - 提醒时间：0（无提醒）
+ * - 修改时间：当前时间戳
+ * - 笔记ID：0（未保存）
+ * - 删除标记：false
+ * - 模式：0（普通文本模式）
+ * - 小组件类型：无效
+ *
+ */
private WorkingNote(Context context, long folderId) {
mContext = context;
mAlertDate = 0;
@@ -114,7 +244,21 @@ public class WorkingNote {
mWidgetType = Notes.TYPE_WIDGET_INVALIDE;
}
- // Existing note construct
+ /**
+ * 加载现有笔记的构造函数。
+ * 功能：初始化一个工作笔记对象，并从数据库加载现有笔记数据。
+ *
+ * @param context 上下文对象，用于访问系统服务
+ * @param noteId 笔记ID，要加载的现有笔记
+ * @param folderId 文件夹ID，笔记所属的文件夹
+ *
+ * 加载流程：
+ *
+ * - 初始化基本字段
+ * - 调用{@link #loadNote()}加载笔记元数据
+ * - 调用{@link #loadNoteData()}加载笔记内容数据
+ *
+ */
private WorkingNote(Context context, long noteId, long folderId) {
mContext = context;
mNoteId = noteId;
@@ -124,6 +268,35 @@ public class WorkingNote {
loadNote();
}
+ /**
+ * 加载笔记的元数据。
+ * 功能：从数据库查询并加载笔记的元数据信息。
+ *
+ * 加载流程：
+ *
+ * - 通过ContentResolver查询{@link Notes#CONTENT_NOTE_URI}获取笔记元数据
+ * - 如果查询成功，提取并保存元数据字段
+ * - 关闭Cursor
+ * - 如果查询失败，记录日志并抛出异常
+ * - 调用{@link #loadNoteData()}加载笔记内容数据
+ *
+ *
+ * 加载的元数据字段：
+ *
+ * - 文件夹ID
+ * - 背景颜色ID
+ * - 小组件ID
+ * - 小组件类型
+ * - 提醒时间
+ * - 修改时间
+ *
+ *
+ * 错误处理：
+ *
+ * - 如果查询失败，记录错误日志
+ * - 抛出IllegalArgumentException异常
+ *
+ */
private void loadNote() {
Cursor cursor = mContext.getContentResolver().query(
ContentUris.withAppendedId(Notes.CONTENT_NOTE_URI, mNoteId), NOTE_PROJECTION, null,
@@ -146,6 +319,30 @@ public class WorkingNote {
loadNoteData();
}
+ /**
+ * 加载笔记的内容数据。
+ * 功能：从数据库查询并加载笔记的内容数据信息。
+ *
+ * 加载流程：
+ *
+ * - 通过ContentResolver查询{@link Notes#CONTENT_DATA_URI}获取笔记内容数据
+ * - 如果查询成功，遍历所有结果
+ * - 根据数据类型处理不同类型的内容数据：
+ *
+ * - 普通笔记：保存内容、模式、文本数据ID
+ * - 通话笔记：保存通话数据ID
+ * - 其他类型：记录日志
+ *
+ * - 关闭Cursor
+ * - 如果查询失败，记录日志并抛出异常
+ *
+ *
+ * 错误处理：
+ *
+ * - 如果查询失败，记录错误日志
+ * - 抛出IllegalArgumentException异常
+ *
+ */
private void loadNoteData() {
Cursor cursor = mContext.getContentResolver().query(Notes.CONTENT_DATA_URI, DATA_PROJECTION,
DataColumns.NOTE_ID + "=?", new String[] {
@@ -174,6 +371,27 @@ public class WorkingNote {
}
}
+ /**
+ * 创建一个空的工作笔记。
+ * 功能：创建一个新的工作笔记对象，并设置默认属性。
+ *
+ * @param context 上下文对象，用于访问系统服务
+ * @param folderId 文件夹ID，新笔记将被添加到该文件夹
+ * @param widgetId 小组件ID，如果笔记关联到小组件
+ * @param widgetType 小组件类型，如果笔记关联到小组件
+ * @param defaultBgColorId 默认背景颜色ID
+ *
+ * @return 创建的工作笔记对象
+ *
+ * 初始化步骤：
+ *
+ * - 创建新的WorkingNote实例
+ * - 设置默认背景颜色
+ * - 设置小组件ID（如果有）
+ * - 设置小组件类型（如果有）
+ * - 返回创建的笔记对象
+ *
+ */
public static WorkingNote createEmptyNote(Context context, long folderId, int widgetId,
int widgetType, int defaultBgColorId) {
WorkingNote note = new WorkingNote(context, folderId);
@@ -183,10 +401,50 @@ public class WorkingNote {
return note;
}
+ /**
+ * 从数据库加载现有笔记。
+ * 功能：根据笔记ID从数据库加载笔记数据，并创建工作笔记对象。
+ *
+ * @param context 上下文对象，用于访问系统服务
+ * @param id 笔记ID，要加载的现有笔记
+ *
+ * @return 加载的工作笔记对象
+ *
+ * 加载流程：
+ *
+ * - 调用构造函数创建WorkingNote实例
+ * - 在构造函数中调用{@link #loadNote()}加载元数据
+ * - 在loadNote()中调用{@link #loadNoteData()}加载内容数据
+ *
+ */
public static WorkingNote load(Context context, long id) {
return new WorkingNote(context, id, 0);
}
+ /**
+ * 保存笔记到数据库。
+ * 功能：将工作笔记的内容和设置保存到数据库中。
+ *
+ * @return 保存是否成功
+ *
+ * 保存流程：
+ *
+ * - 检查笔记是否值得保存（{@link #isWorthSaving()}）
+ * - 如果笔记不存在于数据库：
+ *
+ * - 调用{@link Note#getNewNoteId(Context, long)}获取新笔记ID
+ * - 如果获取失败，记录日志并返回false
+ *
+ * - 调用{@link Note#syncNote(Context, long)}同步笔记数据到数据库
+ * - 如果笔记关联到小组件，通知小组件更新
+ * - 返回保存结果
+ *
+ *
+ * 线程安全：
+ *
+ * - 使用synchronized关键字保证多线程环境下的安全
+ *
+ */
public synchronized boolean saveNote() {
if (isWorthSaving()) {
if (!existInDatabase()) {
@@ -212,10 +470,42 @@ public class WorkingNote {
}
}
+ /**
+ * 检查笔记是否存在于数据库中。
+ * 功能：根据笔记ID判断笔记是否已保存到数据库。
+ *
+ * @return 如果笔记存在于数据库返回true，否则返回false
+ *
+ * 判断逻辑：
+ *
+ * - 笔记ID大于0表示已保存到数据库
+ * - 笔记ID等于0表示未保存到数据库
+ *
+ */
public boolean existInDatabase() {
return mNoteId > 0;
}
+ /**
+ * 检查笔记是否值得保存。
+ * 功能：判断笔记是否需要保存到数据库。
+ *
+ * @return 如果笔记值得保存返回true，否则返回false
+ *
+ * 判断条件：
+ *
+ * - 如果笔记已标记为删除 → 不值得保存
+ * - 如果笔记不存在于数据库且内容为空 → 不值得保存
+ * - 如果笔记存在于数据库但没有本地修改 → 不值得保存
+ * - 其他情况 → 值得保存
+ *
+ *
+ * 优化作用：
+ *
+ * - 避免保存空笔记或未修改的笔记
+ * - 减少不必要的数据库操作
+ *
+ */
private boolean isWorthSaving() {
if (mIsDeleted || (!existInDatabase() && TextUtils.isEmpty(mContent))
|| (existInDatabase() && !mNote.isLocalModified())) {
@@ -225,10 +515,33 @@ public class WorkingNote {
}
}
+ /**
+ * 设置笔记设置变更监听器。
+ * 功能：注册一个监听器，用于接收笔记设置变更的通知。
+ *
+ * @param l 笔记设置变更监听器
+ */
public void setOnSettingStatusChangedListener(NoteSettingChangedListener l) {
mNoteSettingStatusListener = l;
}
+ /**
+ * 设置笔记的提醒时间。
+ * 功能：更新笔记的提醒时间，并通知监听器。
+ *
+ * @param date 提醒时间戳
+ * @param set 是否设置提醒（true表示设置，false表示取消）
+ *
+ * 处理流程：
+ *
+ * - 如果提醒时间发生变化：
+ *
+ * - 更新内部提醒时间字段
+ * - 调用{@link Note#setNoteValue(String, String)}更新笔记元数据
+ *
+ * - 通知监听器提醒时间已变更
+ *
+ */
public void setAlertDate(long date, boolean set) {
if (date != mAlertDate) {
mAlertDate = date;
@@ -239,6 +552,18 @@ public class WorkingNote {
}
}
+ /**
+ * 标记笔记是否已删除。
+ * 功能：设置笔记的删除标记，并通知关联的小组件。
+ *
+ * @param mark 删除标记（true表示已删除，false表示未删除）
+ *
+ * 处理流程：
+ *
+ * - 更新内部删除标记字段
+ * - 如果笔记关联到小组件，通知小组件更新
+ *
+ */
public void markDeleted(boolean mark) {
mIsDeleted = mark;
if (mWidgetId != AppWidgetManager.INVALID_APPWIDGET_ID
@@ -288,56 +613,126 @@ public class WorkingNote {
}
}
+ /**
+ * 将笔记转换为通话笔记。
+ * 功能：设置笔记为通话笔记类型，并添加通话相关信息。
+ *
+ * @param phoneNumber 电话号码
+ * @param callDate 通话时间戳
+ *
+ * 转换流程：
+ *
+ * - 设置通话日期
+ * - 设置电话号码
+ * - 将笔记移动到通话记录文件夹
+ *
+ */
public void convertToCallNote(String phoneNumber, long callDate) {
mNote.setCallData(CallNote.CALL_DATE, String.valueOf(callDate));
mNote.setCallData(CallNote.PHONE_NUMBER, phoneNumber);
mNote.setNoteValue(NoteColumns.PARENT_ID, String.valueOf(Notes.ID_CALL_RECORD_FOLDER));
}
+ /**
+ * 检查笔记是否有提醒。
+ * 功能：判断笔记是否设置了提醒时间。
+ *
+ * @return 如果有提醒返回true，否则返回false
+ *
+ * 判断逻辑：
+ *
+ * - 提醒时间大于0表示有提醒
+ * - 提醒时间等于0表示无提醒
+ *
+ */
public boolean hasClockAlert() {
return (mAlertDate > 0 ? true : false);
}
+ /**
+ * 获取笔记内容。
+ * @return 笔记的内容文本
+ */
public String getContent() {
return mContent;
}
+ /**
+ * 获取笔记的提醒时间。
+ * @return 笔记的提醒时间戳
+ */
public long getAlertDate() {
return mAlertDate;
}
+ /**
+ * 获取笔记的最后修改时间。
+ * @return 笔记的最后修改时间戳
+ */
public long getModifiedDate() {
return mModifiedDate;
}
+ /**
+ * 获取笔记背景颜色的资源ID。
+ * @return 背景颜色的资源ID
+ */
public int getBgColorResId() {
return NoteBgResources.getNoteBgResource(mBgColorId);
}
+ /**
+ * 获取笔记背景颜色的ID。
+ * @return 背景颜色的ID
+ */
public int getBgColorId() {
return mBgColorId;
}
+ /**
+ * 获取笔记标题背景的资源ID。
+ * @return 标题背景的资源ID
+ */
public int getTitleBgResId() {
return NoteBgResources.getNoteTitleBgResource(mBgColorId);
}
+ /**
+ * 获取笔记的清单模式。
+ * @return 清单模式（0表示普通模式，1表示清单模式）
+ */
public int getCheckListMode() {
return mMode;
}
+ /**
+ * 获取笔记的ID。
+ * @return 笔记的唯一标识符
+ */
public long getNoteId() {
return mNoteId;
}
+ /**
+ * 获取笔记所属的文件夹ID。
+ * @return 文件夹ID
+ */
public long getFolderId() {
return mFolderId;
}
+ /**
+ * 获取笔记关联的小组件ID。
+ * @return 小组件ID（无效时返回{@link AppWidgetManager#INVALID_APPWIDGET_ID}）
+ */
public int getWidgetId() {
return mWidgetId;
}
+ /**
+ * 获取笔记关联的小组件类型。
+ * @return 小组件类型（无效时返回{@link Notes#TYPE_WIDGET_INVALIDE}）
+ */
public int getWidgetType() {
return mWidgetType;
}
diff --git a/src/tool/BackupUtils.java b/src/tool/BackupUtils.java
index 39f6ec4..8f3eef8 100644
--- a/src/tool/BackupUtils.java
+++ b/src/tool/BackupUtils.java
@@ -36,11 +36,20 @@ import java.io.IOException;
import java.io.PrintStream;
+/**
+ * 小米便签的备份工具类，用于将便签数据导出为文本文件存储在SD卡，支持文件夹、普通便签、通话记录便签的备份
+ * 采用单例模式，确保全局唯一实例（只有当BackupUtils不存在时才创建）
+ */
public class BackupUtils {
- private static final String TAG = "BackupUtils";
- // Singleton stuff
+ private static final String TAG = "BackupUtils"; // 日志标签
+ // 单例实例
private static BackupUtils sInstance;
+ /**
+ * 获取单例实例
+ * @param context 应用上下文，用于访问资源和数据库，Context让备份工具能够访问便签数据、读取格式模板、写入SD卡，是连接应用逻辑和Android系统的特殊类
+ * @return 全局唯一的BackupUtils实例（只有当BackupUtils不存在时才创建）
+ */
public static synchronized BackupUtils getInstance(Context context) {
if (sInstance == null) {
sInstance = new BackupUtils(context);
@@ -49,251 +58,326 @@ public class BackupUtils {
}
/**
- * Following states are signs to represents backup or restore
- * status
+ * 备份/恢复状态常量，用于标识操作结果
*/
- // Currently, the sdcard is not mounted
+ // SD卡未挂载（无法读写）
public static final int STATE_SD_CARD_UNMOUONTED = 0;
- // The backup file not exist
+ // 备份文件不存在（恢复时使用）
public static final int STATE_BACKUP_FILE_NOT_EXIST = 1;
- // The data is not well formated, may be changed by other programs
+ // 数据格式损坏（可能被其他程序修改）
public static final int STATE_DATA_DESTROIED = 2;
- // Some run-time exception which causes restore or backup fails
+ // 运行时异常导致操作失败
public static final int STATE_SYSTEM_ERROR = 3;
- // Backup or restore success
+ // 备份/恢复成功
public static final int STATE_SUCCESS = 4;
+ // 文本导出的具体实现类
private TextExport mTextExport;
+ /**
+ * 私有构造方法，初始化文本导出工具
+ * @param context 应用上下文
+ */
private BackupUtils(Context context) {
mTextExport = new TextExport(context);
}
+ /**
+ * 检查外部存储（SD卡）是否可用（已挂载且可读写）
+ * @return 可用返回true，否则false
+ */
private static boolean externalStorageAvailable() {
- return Environment.MEDIA_MOUNTED.equals(Environment.getExternalStorageState());
+ return Environment.MEDIA_MOUNTED.equals(Environment.getExternalStorageState());// 返回存储状态
}
+ /**
+ * 对外提供的文本导出入口方法
+ * @return 备份状态（如STATE_SUCCESS、STATE_SD_CARD_UNMOUONTED等）
+ */
public int exportToText() {
return mTextExport.exportToText();
}
+ /**
+ * 获取导出的文本文件名
+ * @return 文件名（如notes_20240520.txt）
+ */
public String getExportedTextFileName() {
return mTextExport.mFileName;
}
+ /**
+ * 获取导出的文本文件所在目录
+ * @return 目录路径（如/sdcard/NotesBackup/）
+ */
public String getExportedTextFileDir() {
return mTextExport.mFileDirectory;
}
+ /**
+ * 静态内部类，封装文本导出的具体逻辑：查询数据库、格式化数据、写入文件
+ */
private static class TextExport {
+ // 查询便签时需要的字段投影（只查询需要的列，优化性能）
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 // 类型（文件夹/便签）
};
+ // 字段索引常量，用于从Cursor中快速获取对应值
private static final int NOTE_COLUMN_ID = 0;
-
private static final int NOTE_COLUMN_MODIFIED_DATE = 1;
-
private static final int NOTE_COLUMN_SNIPPET = 2;
+ // 查询便签详情数据时的字段投影
private static final String[] DATA_PROJECTION = {
- DataColumns.CONTENT,
- DataColumns.MIME_TYPE,
- DataColumns.DATA1,
+ DataColumns.CONTENT, // 内容（文本/位置）
+ DataColumns.MIME_TYPE, // 类型（普通便签/通话便签）
+ DataColumns.DATA1, // 通话便签的通话时间，getFormat函数定义的
DataColumns.DATA2,
- DataColumns.DATA3,
+ DataColumns.DATA3, // 通话便签的电话号码，getFormat函数定义的
DataColumns.DATA4,
};
+ /*
+ * private String getFormat(int id) {
+ return TEXT_FORMAT[id];
+ }*/
+ // 数据字段索引常量
private static final int DATA_COLUMN_CONTENT = 0;
-
private static final int DATA_COLUMN_MIME_TYPE = 1;
+ private static final int DATA_COLUMN_CALL_DATE = 2; // 通话时间在DATA1中，getFormat函数定义的
+ private static final int DATA_COLUMN_PHONE_NUMBER = 4; // 电话号码在DATA3中，getFormat函数定义的
- private static final int DATA_COLUMN_CALL_DATE = 2;
-
- private static final int DATA_COLUMN_PHONE_NUMBER = 4;
-
+ // 文本格式化模板（从资源文件读取，如文件夹名、时间、内容的格式）
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 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; // 导出的文件目录
+ /**
+ * 初始化文本导出工具
+ * @param context 上下文，用于获取资源和查询数据库
+ */
public TextExport(Context context) {
+ // 从资源文件读取格式化模板（如strings.xml中的format_for_exported_note数组）
TEXT_FORMAT = context.getResources().getStringArray(R.array.format_for_exported_note);
mContext = context;
mFileName = "";
mFileDirectory = "";
}
+ /**
+ * 获取指定索引的格式化模板
+ * @param id 模板索引（如FORMAT_FOLDER_NAME）
+ * @return 模板字符串
+ */
private String getFormat(int id) {
return TEXT_FORMAT[id];
}
/**
- * Export the folder identified by folder id to text
+ * 导出指定文件夹下的所有便签到输出流
+ * @param folderId 文件夹ID
+ * @param ps 输出流（指向备份文件）
*/
private void exportFolderToText(String folderId, PrintStream ps) {
- // Query notes belong to this folder
- Cursor notesCursor = mContext.getContentResolver().query(Notes.CONTENT_NOTE_URI,
- NOTE_PROJECTION, NoteColumns.PARENT_ID + "=?", new String[] {
- folderId
- }, null);
+ // 查询该文件夹下的所有便签（通过parent_id关联）
+ Cursor notesCursor = mContext.getContentResolver().query(
+ Notes.CONTENT_NOTE_URI, // 便签数据库的URI
+ NOTE_PROJECTION, // 要查询的字段
+ NoteColumns.PARENT_ID + "=?", // 查询条件：parent_id=folderId
+ new String[] {folderId}, // 条件参数
+ null); // 排序方式（默认）
if (notesCursor != null) {
- if (notesCursor.moveToFirst()) {
+ if (notesCursor.moveToFirst()) { // 遍历所有便签
do {
- // Print note's last modified date
- ps.println(String.format(getFormat(FORMAT_NOTE_DATE), DateFormat.format(
- mContext.getString(R.string.format_datetime_mdhm),
- notesCursor.getLong(NOTE_COLUMN_MODIFIED_DATE))));
- // Query data belong to this note
+ // 打印便签的最后修改时间（格式化显示）
+ ps.println(String.format(
+ getFormat(FORMAT_NOTE_DATE),
+ DateFormat.format(
+ mContext.getString(R.string.format_datetime_mdhm), // 时间格式（月日时分）
+ notesCursor.getLong(NOTE_COLUMN_MODIFIED_DATE)
+ )
+ ));
+ // 导出该便签的详细内容
String noteId = notesCursor.getString(NOTE_COLUMN_ID);
exportNoteToText(noteId, ps);
} while (notesCursor.moveToNext());
}
- notesCursor.close();
+ notesCursor.close(); // 关闭游标，释放资源
}
}
/**
- * Export note identified by id to a print stream
+ * 导出单个便签的详细内容到输出流
+ * 区分普通便签和通话便签，分别格式化内容
+ * @param noteId 便签ID
+ * @param ps 输出流（指向备份文件）
*/
private void exportNoteToText(String noteId, PrintStream ps) {
- Cursor dataCursor = mContext.getContentResolver().query(Notes.CONTENT_DATA_URI,
- DATA_PROJECTION, DataColumns.NOTE_ID + "=?", new String[] {
- noteId
- }, null);
+ // 查询该便签的详细数据（如文本内容、通话记录信息）
+ Cursor dataCursor = mContext.getContentResolver().query(
+ Notes.CONTENT_DATA_URI, // 便签数据的URI
+ DATA_PROJECTION, // 要查询的字段
+ DataColumns.NOTE_ID + "=?", // 查询条件：note_id=noteId
+ new String[] {noteId}, // 条件参数
+ null); // 排序方式
if (dataCursor != null) {
- if (dataCursor.moveToFirst()) {
+ if (dataCursor.moveToFirst()) { // 遍历便签的所有数据
do {
String mimeType = dataCursor.getString(DATA_COLUMN_MIME_TYPE);
- if (DataConstants.CALL_NOTE.equals(mimeType)) {
- // Print phone number
+ if (DataConstants.CALL_NOTE.equals(mimeType)) { // 通话记录便签
+ // 提取电话号码、通话时间、位置信息
String phoneNumber = dataCursor.getString(DATA_COLUMN_PHONE_NUMBER);
long callDate = dataCursor.getLong(DATA_COLUMN_CALL_DATE);
String location = dataCursor.getString(DATA_COLUMN_CONTENT);
+ // 打印电话号码（非空时）
if (!TextUtils.isEmpty(phoneNumber)) {
- ps.println(String.format(getFormat(FORMAT_NOTE_CONTENT),
- phoneNumber));
+ ps.println(String.format(getFormat(FORMAT_NOTE_CONTENT), phoneNumber));
}
- // Print call date
- ps.println(String.format(getFormat(FORMAT_NOTE_CONTENT), DateFormat
- .format(mContext.getString(R.string.format_datetime_mdhm),
- callDate)));
- // Print call attachment location
+ // 打印通话时间（格式化）
+ ps.println(String.format(
+ getFormat(FORMAT_NOTE_CONTENT),
+ DateFormat.format(
+ mContext.getString(R.string.format_datetime_mdhm),
+ callDate
+ )
+ ));
+ // 打印位置信息（非空时）
if (!TextUtils.isEmpty(location)) {
- ps.println(String.format(getFormat(FORMAT_NOTE_CONTENT),
- location));
+ ps.println(String.format(getFormat(FORMAT_NOTE_CONTENT), location));
}
- } else if (DataConstants.NOTE.equals(mimeType)) {
+ } 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),
- content));
+ if (!TextUtils.isEmpty(content)) { // 打印文本内容
+ ps.println(String.format(getFormat(FORMAT_NOTE_CONTENT), content));
}
}
} while (dataCursor.moveToNext());
}
- dataCursor.close();
+ dataCursor.close(); // 关闭游标，释放资源
}
- // print a line separator between note
+ // 便签之间添加分隔符（换行）
try {
- ps.write(new byte[] {
- Character.LINE_SEPARATOR, Character.LETTER_NUMBER
- });
+ ps.write(new byte[] {Character.LINE_SEPARATOR, Character.LINE_SEPARATOR});
} catch (IOException e) {
- Log.e(TAG, e.toString());
+ Log.e(TAG, "写入分隔符失败：" + e.toString());
}
}
/**
- * Note will be exported as text which is user readable
+ * 执行文本导出的主逻辑：检查SD卡→创建文件→查询数据→写入文件
+ * @return 备份状态（如STATE_SUCCESS）
*/
public int exportToText() {
+ // 检查SD卡是否可用
if (!externalStorageAvailable()) {
- Log.d(TAG, "Media was not mounted");
+ Log.d(TAG, "SD卡未挂载，无法导出");
return STATE_SD_CARD_UNMOUONTED;
}
+ // 获取指向备份文件的输出流
PrintStream ps = getExportToTextPrintStream();
if (ps == null) {
- Log.e(TAG, "get print stream error");
+ Log.e(TAG, "创建输出流失败");
return STATE_SYSTEM_ERROR;
}
- // First export folder and its notes
+
+ // 1. 导出所有文件夹及其包含的便签（排除回收站，包含通话记录文件夹）
Cursor folderCursor = mContext.getContentResolver().query(
Notes.CONTENT_NOTE_URI,
NOTE_PROJECTION,
+ // 查询条件：文件夹类型且不在回收站，或通话记录文件夹
"(" + NoteColumns.TYPE + "=" + Notes.TYPE_FOLDER + " AND "
+ NoteColumns.PARENT_ID + "<>" + Notes.ID_TRASH_FOLER + ") OR "
- + NoteColumns.ID + "=" + Notes.ID_CALL_RECORD_FOLDER, null, null);
+ + NoteColumns.ID + "=" + Notes.ID_CALL_RECORD_FOLDER,
+ null,
+ null);
if (folderCursor != null) {
- if (folderCursor.moveToFirst()) {
+ if (folderCursor.moveToFirst()) { // 遍历所有文件夹
do {
- // Print folder's name
+ // 获取文件夹名（通话记录文件夹使用固定名称）
String folderName = "";
- if(folderCursor.getLong(NOTE_COLUMN_ID) == Notes.ID_CALL_RECORD_FOLDER) {
- folderName = mContext.getString(R.string.call_record_folder_name);
+ if (folderCursor.getLong(NOTE_COLUMN_ID) == Notes.ID_CALL_RECORD_FOLDER) {
+ folderName = mContext.getString(R.string.call_record_folder_name); // 从资源获取“通话记录”
} else {
- folderName = folderCursor.getString(NOTE_COLUMN_SNIPPET);
+ 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());
}
- folderCursor.close();
+ folderCursor.close(); // 关闭游标
}
- // Export notes in root's folder
+ // 2. 导出根目录下的便签（无文件夹归属的便签，parent_id=0）
Cursor noteCursor = mContext.getContentResolver().query(
Notes.CONTENT_NOTE_URI,
NOTE_PROJECTION,
- NoteColumns.TYPE + "=" + +Notes.TYPE_NOTE + " AND " + NoteColumns.PARENT_ID
- + "=0", null, null);
+ NoteColumns.TYPE + "=" + Notes.TYPE_NOTE + " AND " + NoteColumns.PARENT_ID + "=0",
+ null,
+ null);
if (noteCursor != null) {
- if (noteCursor.moveToFirst()) {
+ 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))));
- // Query data belong to this note
+ // 打印修改时间
+ ps.println(String.format(
+ getFormat(FORMAT_NOTE_DATE),
+ DateFormat.format(
+ mContext.getString(R.string.format_datetime_mdhm),
+ noteCursor.getLong(NOTE_COLUMN_MODIFIED_DATE)
+ )
+ ));
+ // 导出便签内容
String noteId = noteCursor.getString(NOTE_COLUMN_ID);
exportNoteToText(noteId, ps);
} while (noteCursor.moveToNext());
}
- noteCursor.close();
+ noteCursor.close(); // 关闭游标
}
- ps.close();
- return STATE_SUCCESS;
+ ps.close(); // 关闭输出流
+ return STATE_SUCCESS; // 导出成功
}
/**
- * Get a print stream pointed to the file {@generateExportedTextFile}
+ * 创建SD卡上的备份文件，并返回指向该文件的PrintStream
+ * @return 输出流（PrintStream），失败返回null
*/
private PrintStream getExportToTextPrintStream() {
- File file = generateFileMountedOnSDcard(mContext, R.string.file_path,
- R.string.file_name_txt_format);
+ // 在SD卡上生成备份文件（路径和名称从资源获取，包含当前日期）
+ File file = generateFileMountedOnSDcard(
+ mContext,
+ R.string.file_path, // 目录路径（如/sdcard/NotesBackup/）
+ R.string.file_name_txt_format // 文件名格式（如notes_%s.txt，%s为日期）
+ );
if (file == null) {
- Log.e(TAG, "create file to exported failed");
+ Log.e(TAG, "创建备份文件失败");
return null;
}
+ // 记录文件名和目录
mFileName = file.getName();
mFileDirectory = mContext.getString(R.string.file_path);
+
+ // 创建输出流
PrintStream ps = null;
try {
FileOutputStream fos = new FileOutputStream(file);
@@ -310,35 +394,43 @@ public class BackupUtils {
}
/**
- * Generate the text file to store imported data
+ * 在SD卡上创建备份文件（含目录）
+ * @param context 上下文
+ * @param filePathResId 目录路径的资源ID（如R.string.file_path）
+ * @param fileNameFormatResId 文件名格式的资源ID（如R.string.file_name_txt_format）
+ * @return 创建的文件，失败返回null
*/
private static File generateFileMountedOnSDcard(Context context, int filePathResId, int fileNameFormatResId) {
StringBuilder sb = new StringBuilder();
+ // 拼接路径：SD卡根目录 + 应用备份目录（如/sdcard/NotesBackup/）
sb.append(Environment.getExternalStorageDirectory());
sb.append(context.getString(filePathResId));
File filedir = new File(sb.toString());
+
+ // 拼接文件名：目录 + 格式化名称（含当前日期，如notes_20240520.txt）
sb.append(context.getString(
fileNameFormatResId,
- DateFormat.format(context.getString(R.string.format_date_ymd),
- System.currentTimeMillis())));
+ DateFormat.format(
+ context.getString(R.string.format_date_ymd), // 日期格式（年月日）
+ System.currentTimeMillis()
+ )
+ ));
File file = new File(sb.toString());
+ // 创建目录和文件
try {
if (!filedir.exists()) {
- filedir.mkdir();
+ filedir.mkdir(); // 目录不存在则创建
}
if (!file.exists()) {
- file.createNewFile();
+ file.createNewFile(); // 文件不存在则创建
}
return file;
} catch (SecurityException e) {
- e.printStackTrace();
+ e.printStackTrace(); // 权限不足
} catch (IOException e) {
- e.printStackTrace();
+ e.printStackTrace(); // 创建文件失败
}
-
return null;
}
-}
-
-
+}
\ No newline at end of file
diff --git a/src/tool/DataUtils.java b/src/tool/DataUtils.java
index 2a14982..1aa2572 100644
--- a/src/tool/DataUtils.java
+++ b/src/tool/DataUtils.java
@@ -35,88 +35,127 @@ import java.util.ArrayList;
import java.util.HashSet;
+
+
+/**
+ * 便签数据操作工具类，封装数据库查询、更新、删除等常用操作，
+ * 提供与ContentProvider交互的统一接口，支撑UI层的数据需求
+ */
public class DataUtils {
public static final String TAG = "DataUtils";
+
+ /**
+ * 批量删除便签或文件夹（跳过系统根目录）
+ * @param resolver 内容解析器，用于操作数据库
+ * @param ids 待删除的便签/文件夹ID集合
+ * @return 操作成功返回true，失败返回false
+ */
public static boolean batchDeleteNotes(ContentResolver resolver, HashSet ids) {
if (ids == null) {
- Log.d(TAG, "the ids is null");
+ Log.d(TAG, "待删除的ID集合为null");
return true;
}
if (ids.size() == 0) {
- Log.d(TAG, "no id is in the hashset");
+ Log.d(TAG, "待删除的ID集合为空");
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");
+ Log.e(TAG, "不能删除系统根目录文件夹");
continue;
}
+ // 构建删除操作（根据ID删除便签）
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());
+ Log.d(TAG, "删除失败，ID集合:" + ids.toString());
return false;
}
return true;
} catch (RemoteException e) {
- Log.e(TAG, String.format("%s: %s", e.toString(), e.getMessage()));
+ Log.e(TAG, String.format("远程异常: %s: %s", e.toString(), e.getMessage()));
} catch (OperationApplicationException e) {
- Log.e(TAG, String.format("%s: %s", e.toString(), e.getMessage()));
+ Log.e(TAG, String.format("操作应用异常: %s: %s", e.toString(), e.getMessage()));
}
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");
+ Log.d(TAG, "待移动的ID集合为null");
return true;
}
+ // 创建批量更新操作列表
ArrayList operationList = new ArrayList();
for (long id : ids) {
+ // 构建更新操作（修改父目录ID）
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.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());
+ Log.d(TAG, "移动失败，ID集合:" + ids.toString());
return false;
}
return true;
} catch (RemoteException e) {
- Log.e(TAG, String.format("%s: %s", e.toString(), e.getMessage()));
+ Log.e(TAG, String.format("远程异常: %s: %s", e.toString(), e.getMessage()));
} catch (OperationApplicationException e) {
- Log.e(TAG, String.format("%s: %s", e.toString(), e.getMessage()));
+ Log.e(TAG, String.format("操作应用异常: %s: %s", e.toString(), e.getMessage()));
}
return false;
}
/**
- * 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(*)" },
+ new String[] { "COUNT(*)" }, // 统计数量
NoteColumns.TYPE + "=? AND " + NoteColumns.PARENT_ID + "<>?",
new String[] { String.valueOf(Notes.TYPE_FOLDER), String.valueOf(Notes.ID_TRASH_FOLER)},
null);
@@ -127,7 +166,7 @@ public class DataUtils {
try {
count = cursor.getInt(0);
} catch (IndexOutOfBoundsException e) {
- Log.e(TAG, "get folder count failed:" + e.toString());
+ Log.e(TAG, "获取文件夹数量失败:" + e.toString());
} finally {
cursor.close();
}
@@ -136,6 +175,13 @@ public class DataUtils {
return count;
}
+ /**
+ * 检查便签是否存在且可见（不在垃圾站中）
+ * @param resolver 内容解析器
+ * @param noteId 便签ID
+ * @param type 便签类型（如Notes.TYPE_NOTE）
+ * @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,
@@ -145,62 +191,78 @@ public class DataUtils {
boolean exist = false;
if (cursor != null) {
- if (cursor.getCount() > 0) {
- exist = true;
- }
+ exist = cursor.getCount() > 0; // 游标有数据则存在
cursor.close();
}
return exist;
}
+ /**
+ * 检查便签是否存在（包括垃圾站中的便签）
+ * @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);
boolean exist = false;
if (cursor != null) {
- if (cursor.getCount() > 0) {
- exist = true;
- }
+ exist = cursor.getCount() > 0;
cursor.close();
}
return exist;
}
+ /**
+ * 检查便签内容数据是否存在
+ * @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);
boolean exist = false;
if (cursor != null) {
- if (cursor.getCount() > 0) {
- exist = true;
- }
+ exist = cursor.getCount() > 0;
cursor.close();
}
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 + "=?", // SNIPPET字段存储文件夹名称
new String[] { name }, null);
boolean exist = false;
if(cursor != null) {
- if(cursor.getCount() > 0) {
- exist = true;
- }
+ exist = cursor.getCount() > 0;
cursor.close();
}
return exist;
}
+ /**
+ * 获取文件夹下所有便签关联的桌面小部件属性
+ * @param resolver 内容解析器
+ * @param folderId 文件夹ID
+ * @return 小部件属性集合（包含widgetId和widgetType）
+ */
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 + "=?",
+ new String[] { NoteColumns.WIDGET_ID, NoteColumns.WIDGET_TYPE }, // 查询小部件ID和类型
+ NoteColumns.PARENT_ID + "=?", // 筛选指定文件夹下的便签
new String[] { String.valueOf(folderId) },
null);
@@ -224,10 +286,16 @@ 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 + "=?",
+ new String [] { CallNote.PHONE_NUMBER }, // 查询电话号码字段
+ CallNote.NOTE_ID + "=? AND " + CallNote.MIME_TYPE + "=?", // 筛选通话便签数据
new String [] { String.valueOf(noteId), CallNote.CONTENT_ITEM_TYPE },
null);
@@ -235,7 +303,7 @@ public class DataUtils {
try {
return cursor.getString(0);
} catch (IndexOutOfBoundsException e) {
- Log.e(TAG, "Get call number fails " + e.toString());
+ Log.e(TAG, "获取电话号码失败 " + e.toString());
} finally {
cursor.close();
}
@@ -243,11 +311,18 @@ public class DataUtils {
return "";
}
+ /**
+ * 通过电话号码和通话时间查找对应的通话便签ID（避免重复创建）
+ * @param resolver 内容解析器
+ * @param phoneNumber 电话号码
+ * @param callDate 通话时间戳
+ * @return 便签ID，未找到返回0
+ */
public static long getNoteIdByPhoneNumberAndCallDate(ContentResolver resolver, String phoneNumber, long callDate) {
Cursor cursor = resolver.query(Notes.CONTENT_DATA_URI,
- new String [] { CallNote.NOTE_ID },
+ new String [] { CallNote.NOTE_ID }, // 查询关联的便签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);
@@ -256,7 +331,7 @@ public class DataUtils {
try {
return cursor.getLong(0);
} catch (IndexOutOfBoundsException e) {
- Log.e(TAG, "Get call note id fails " + e.toString());
+ Log.e(TAG, "获取通话便签ID失败 " + e.toString());
}
}
cursor.close();
@@ -264,9 +339,15 @@ public class DataUtils {
return 0;
}
+ /**
+ * 通过便签ID获取摘要文本（用于列表页展示）
+ * @param resolver 内容解析器
+ * @param noteId 便签ID
+ * @return 摘要文本，便签不存在则抛出异常
+ */
public static String getSnippetById(ContentResolver resolver, long noteId) {
Cursor cursor = resolver.query(Notes.CONTENT_NOTE_URI,
- new String [] { NoteColumns.SNIPPET },
+ new String [] { NoteColumns.SNIPPET }, // 查询摘要字段
NoteColumns.ID + "=?",
new String [] { String.valueOf(noteId)},
null);
@@ -279,17 +360,22 @@ public class DataUtils {
cursor.close();
return snippet;
}
- throw new IllegalArgumentException("Note is not found with id: " + noteId);
+ throw new IllegalArgumentException("未找到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/tool/GTaskStringUtils.java b/src/tool/GTaskStringUtils.java
index 666b729..37a6856 100644
--- a/src/tool/GTaskStringUtils.java
+++ b/src/tool/GTaskStringUtils.java
@@ -13,101 +13,157 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
-
package net.micode.notes.tool;
+/**
+ * GTask字符串常量工具类，定义小米便签与GTask（Google Tasks）同步过程中使用的所有标识符
+ * 包括JSON键名、文件夹标识、元数据键等，用于统一同步过程中的数据交互格式
+ */
public class GTaskStringUtils {
+ // ========================== GTask JSON动作相关键名 ==========================
+ /** JSON中动作ID的键名，用于标识同步操作的唯一ID（如创建/更新任务的动作ID） */
public final static String GTASK_JSON_ACTION_ID = "action_id";
+ /** JSON中动作列表的键名，用于包装多个同步动作（如批量创建/更新任务） */
public final static String GTASK_JSON_ACTION_LIST = "action_list";
+ /** JSON中动作类型的键名，用于标识当前动作是创建/更新/移动等类型 */
public final static String GTASK_JSON_ACTION_TYPE = "action_type";
+ /** 动作类型：创建操作，用于标识在GTask中创建新任务或文件夹 */
public final static String GTASK_JSON_ACTION_TYPE_CREATE = "create";
+ /** 动作类型：获取全部数据，用于请求GTask中的所有任务和文件夹数据 */
public final static String GTASK_JSON_ACTION_TYPE_GETALL = "get_all";
+ /** 动作类型：移动操作，用于标识将任务/文件夹移动到新位置 */
public final static String GTASK_JSON_ACTION_TYPE_MOVE = "move";
+ /** 动作类型：更新操作，用于标识修改GTask中已有的任务或文件夹 */
public final static String GTASK_JSON_ACTION_TYPE_UPDATE = "update";
+
+ // ========================== GTask JSON实体属性相关键名 ==========================
+ /** JSON中创建者ID的键名，标识任务/文件夹的创建者（小米便签中暂用"null"） */
public final static String GTASK_JSON_CREATOR_ID = "creator_id";
+ /** JSON中子实体的键名，用于存储子任务信息 */
public final static String GTASK_JSON_CHILD_ENTITY = "child_entity";
+ /** JSON中客户端版本的键名，标识当前同步客户端的版本 */
public final static String GTASK_JSON_CLIENT_VERSION = "client_version";
+ /** JSON中任务完成状态的键名，标识任务是否已完成（true/false） */
public final static String GTASK_JSON_COMPLETED = "completed";
+ /** JSON中当前列表ID的键名，标识当前操作的任务列表ID */
public final static String GTASK_JSON_CURRENT_LIST_ID = "current_list_id";
+ /** JSON中默认列表ID的键名，标识GTask中的默认任务列表ID */
public final static String GTASK_JSON_DEFAULT_LIST_ID = "default_list_id";
+ /** JSON中删除状态的键名，标识任务/文件夹是否已删除（true/false） */
public final static String GTASK_JSON_DELETED = "deleted";
+ /** JSON中目标列表的键名，用于移动操作时指定目标列表 */
public final static String GTASK_JSON_DEST_LIST = "dest_list";
+ /** JSON中目标父节点的键名，用于移动操作时指定目标父节点 */
public final static String GTASK_JSON_DEST_PARENT = "dest_parent";
+ /** JSON中目标父节点类型的键名，标识目标父节点是任务（TASK）还是文件夹（GROUP） */
public final static String GTASK_JSON_DEST_PARENT_TYPE = "dest_parent_type";
+ /** JSON中实体增量的键名，用于存储任务/文件夹的修改内容（如名称、状态等） */
public final static String GTASK_JSON_ENTITY_DELTA = "entity_delta";
+ /** JSON中实体类型的键名，标识当前实体是任务（TASK）还是文件夹（GROUP） */
public final static String GTASK_JSON_ENTITY_TYPE = "entity_type";
+ /** JSON中获取已删除实体的键名，用于请求GTask中已删除的任务/文件夹 */
public final static String GTASK_JSON_GET_DELETED = "get_deleted";
+ /** JSON中实体ID的键名，标识任务/文件夹在GTask中的唯一ID */
public final static String GTASK_JSON_ID = "id";
+ /** JSON中排序索引的键名，标识任务/文件夹在列表中的位置（用于排序） */
public final static String GTASK_JSON_INDEX = "index";
+ /** JSON中最后修改时间的键名，标识任务/文件夹的最近修改时间（用于同步冲突判断） */
public final static String GTASK_JSON_LAST_MODIFIED = "last_modified";
+ /** JSON中最新同步点的键名，标识上次同步的时间点（用于增量同步） */
public final static String GTASK_JSON_LATEST_SYNC_POINT = "latest_sync_point";
+ /** JSON中列表ID的键名，标识当前任务所属的列表ID */
public final static String GTASK_JSON_LIST_ID = "list_id";
+ /** JSON中列表集合的键名，用于存储多个任务列表数据 */
public final static String GTASK_JSON_LISTS = "lists";
+ /** JSON中名称的键名，标识任务/文件夹的名称 */
public final static String GTASK_JSON_NAME = "name";
+ /** JSON中新ID的键名，用于标识创建操作后GTask返回的新实体ID */
public final static String GTASK_JSON_NEW_ID = "new_id";
+ /** JSON中备注的键名，标识任务的备注内容 */
public final static String GTASK_JSON_NOTES = "notes";
+ /** JSON中父节点ID的键名，标识当前实体的父节点ID（用于层级结构） */
public final static String GTASK_JSON_PARENT_ID = "parent_id";
+ /** JSON中前序兄弟节点ID的键名，标识当前实体的前一个兄弟节点（用于排序） */
public final static String GTASK_JSON_PRIOR_SIBLING_ID = "prior_sibling_id";
+ /** JSON中结果集合的键名，用于存储GTask返回的同步结果 */
public final static String GTASK_JSON_RESULTS = "results";
+ /** JSON中源列表的键名，用于移动操作时指定源列表 */
public final static String GTASK_JSON_SOURCE_LIST = "source_list";
+ /** JSON中任务集合的键名，用于存储多个任务数据 */
public final static String GTASK_JSON_TASKS = "tasks";
+ /** JSON中类型的键名，与ENTITY_TYPE配合使用 */
public final static String GTASK_JSON_TYPE = "type";
+ /** 实体类型：文件夹（分组），标识当前实体是GTask中的文件夹 */
public final static String GTASK_JSON_TYPE_GROUP = "GROUP";
+ /** 实体类型：任务，标识当前实体是GTask中的任务 */
public final static String GTASK_JSON_TYPE_TASK = "TASK";
+ /** JSON中用户信息的键名，标识当前同步的用户 */
public final static String GTASK_JSON_USER = "user";
+
+ // ========================== 小米便签专属文件夹标识 ==========================
+ /** 小米便签文件夹前缀，用于在GTask中区分小米便签创建的文件夹（避免与其他应用冲突） */
public final static String MIUI_FOLDER_PREFFIX = "[MIUI_Notes]";
+ /** 小米便签默认文件夹名称，拼接前缀后为"[MIUI_Notes]Default" */
public final static String FOLDER_DEFAULT = "Default";
+ /** 小米便签通话记录文件夹名称，拼接前缀后为"[MIUI_Notes]Call_Note" */
public final static String FOLDER_CALL_NOTE = "Call_Note";
+ /** 小米便签元数据文件夹名称，用于存储便签的额外信息（如本地ID、附件信息等） */
public final static String FOLDER_META = "METADATA";
+
+ // ========================== 元数据相关键名 ==========================
+ /** 元数据中GTask ID的键名，用于存储实体在GTask中的ID */
public final static String META_HEAD_GTASK_ID = "meta_gid";
+ /** 元数据中便签信息的键名，用于存储便签的核心信息（如ID、类型等） */
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/tool/ResourceParser.java b/src/tool/ResourceParser.java
index 1ad3ad6..af06daf 100644
--- a/src/tool/ResourceParser.java
+++ b/src/tool/ResourceParser.java
@@ -22,151 +22,238 @@ import android.preference.PreferenceManager;
import net.micode.notes.R;
import net.micode.notes.ui.NotesPreferenceActivity;
+/**
+ * 资源解析器：统一管理便签应用中的各类资源（背景、文字样式等）
+ * 提供资源获取接口，实现样式资源与业务逻辑的解耦
+ */
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 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 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 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 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 // 红色标题栏
};
+ /**
+ * 获取便签编辑页主体背景资源
+ * @param id 颜色标识（如YELLOW、BLUE等）
+ * @return 背景图片资源ID
+ */
public static int getNoteBgResource(int id) {
return BG_EDIT_RESOURCES[id];
}
+ /**
+ * 获取便签编辑页标题栏背景资源
+ * @param id 颜色标识（如YELLOW、BLUE等）
+ * @return 标题栏背景图片资源ID
+ */
public static int getNoteTitleBgResource(int id) {
return BG_EDIT_TITLE_RESOURCES[id];
}
}
+ /**
+ * 获取默认背景颜色ID
+ * 根据用户设置判断：若开启随机背景，则返回随机颜色；否则返回默认黄色
+ * @param context 上下文
+ * @return 背景颜色标识
+ */
public static int getDefaultBgId(Context context) {
if (PreferenceManager.getDefaultSharedPreferences(context).getBoolean(
NotesPreferenceActivity.PREFERENCE_SET_BG_COLOR_KEY, false)) {
+ // 随机选择背景颜色（0到背景资源数量-1之间）
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 颜色标识
+ * @return 首项背景资源ID
+ */
public static int getNoteBgFirstRes(int id) {
return BG_FIRST_RESOURCES[id];
}
+ /**
+ * 获取列表末项背景资源
+ * @param id 颜色标识
+ * @return 末项背景资源ID
+ */
public static int getNoteBgLastRes(int id) {
return BG_LAST_RESOURCES[id];
}
+ /**
+ * 获取列表唯一项背景资源
+ * @param id 颜色标识
+ * @return 唯一项背景资源ID
+ */
public static int getNoteBgSingleRes(int id) {
return BG_SINGLE_RESOURCES[id];
}
+ /**
+ * 获取列表中间项背景资源
+ * @param 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;
}
}
+ /**
+ * 桌面小部件（Widget）背景资源管理
+ * 提供不同尺寸Widget的背景资源
+ */
public static class WidgetBgResources {
+ // 2x尺寸Widget背景资源数组
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黄色Widget
+ R.drawable.widget_2x_blue, // 2x蓝色Widget
+ R.drawable.widget_2x_white, // 2x白色Widget
+ R.drawable.widget_2x_green, // 2x绿色Widget
+ R.drawable.widget_2x_red, // 2x红色Widget
};
+ /**
+ * 获取2x尺寸Widget背景资源
+ * @param id 颜色标识
+ * @return 2x Widget背景资源ID
+ */
public static int getWidget2xBgResource(int id) {
return BG_2X_RESOURCES[id];
}
+ // 4x尺寸Widget背景资源数组
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黄色Widget
+ R.drawable.widget_4x_blue, // 4x蓝色Widget
+ R.drawable.widget_4x_white, // 4x白色Widget
+ R.drawable.widget_4x_green, // 4x绿色Widget
+ R.drawable.widget_4x_red // 4x红色Widget
};
+ /**
+ * 获取4x尺寸Widget背景资源
+ * @param id 颜色标识
+ * @return 4x Widget背景资源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 // 超大字体样式
};
+ /**
+ * 获取文字样式资源
+ * @param id 字体大小标识（如TEXT_SMALL、TEXT_MEDIUM等）
+ * @return 文字样式资源ID（若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}
+ * 兼容处理：防止存储的资源ID超出范围
+ * 若id无效，返回默认字体大小样式
*/
if (id >= TEXTAPPEARANCE_RESOURCES.length) {
return BG_DEFAULT_FONT_SIZE;
@@ -174,8 +261,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/ui/AlarmAlertActivity.java b/src/ui/AlarmAlertActivity.java
index 85723be..c0e7362 100644
--- a/src/ui/AlarmAlertActivity.java
+++ b/src/ui/AlarmAlertActivity.java
@@ -40,20 +40,31 @@ import net.micode.notes.tool.DataUtils;
import java.io.IOException;
+/**
+ * 便签提醒活动页，负责在便签提醒时间到达时显示提醒对话框并播放闹钟声音
+ * 实现对话框按钮点击监听和对话框消失监听，处理用户操作
+ */
public class AlarmAlertActivity extends Activity implements OnClickListener, OnDismissListener {
+ // 提醒的便签ID
private long mNoteId;
+ // 便签内容摘要（用于提醒对话框展示）
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);
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
@@ -61,11 +72,15 @@ public class AlarmAlertActivity extends Activity implements OnClickListener, OnD
| WindowManager.LayoutParams.FLAG_LAYOUT_INSET_DECOR);
}
+ // 获取启动当前Activity的Intent（由AlarmReceiver传递）
Intent intent = getIntent();
try {
+ // 从Intent的Data中解析便签ID（Data格式为content://.../notes/{id}，取路径的第2段）
mNoteId = Long.valueOf(intent.getData().getPathSegments().get(1));
+ // 通过便签ID获取内容摘要（用于提醒展示）
mSnippet = DataUtils.getSnippetById(this.getContentResolver(), mNoteId);
+ // 处理摘要长度：超过最大长度时截断并添加省略提示
mSnippet = mSnippet.length() > SNIPPET_PREW_MAX_LEN ? mSnippet.substring(0,
SNIPPET_PREW_MAX_LEN) + getResources().getString(R.string.notelist_string_info)
: mSnippet;
@@ -74,85 +89,115 @@ public class AlarmAlertActivity extends Activity implements OnClickListener, OnD
return;
}
+ // 初始化媒体播放器
mPlayer = new MediaPlayer();
+ // 检查便签是否存在且可见（未被删除）
if (DataUtils.visibleInNoteDatabase(getContentResolver(), mNoteId, Notes.TYPE_NOTE)) {
+ // 显示提醒对话框
showActionDialog();
+ // 播放闹钟声音
playAlarmSound();
} else {
+ // 便签不存在则直接结束活动
finish();
}
}
+ /**
+ * 判断屏幕是否处于亮屏状态
+ * @return 屏幕亮着返回true，否则返回false
+ */
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();
- } 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
+ } catch (IllegalArgumentException | SecurityException | IllegalStateException | IOException e) {
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);
+ // 若屏幕亮着，添加“进入”按钮（跳转到便签编辑页）
if (isScreenOn()) {
dialog.setNegativeButton(R.string.notealert_enter, this);
}
+ // 显示对话框，并设置消失监听（用于停止铃声）
dialog.show().setOnDismissListener(this);
}
+ /**
+ * 处理对话框按钮点击事件
+ * @param dialog 对话框实例
+ * @param which 点击的按钮标识（BUTTON_POSITIVE/BUTTON_NEGATIVE）
+ */
public void onClick(DialogInterface dialog, int which) {
switch (which) {
+ // 点击“进入”按钮：跳转到便签编辑页查看完整内容
case DialogInterface.BUTTON_NEGATIVE:
Intent intent = new Intent(this, NoteEditActivity.class);
- intent.setAction(Intent.ACTION_VIEW);
- intent.putExtra(Intent.EXTRA_UID, mNoteId);
+ intent.setAction(Intent.ACTION_VIEW); // 动作：查看便签
+ intent.putExtra(Intent.EXTRA_UID, mNoteId); // 传递便签ID
startActivity(intent);
break;
+ // 点击“确定”按钮：默认不做额外操作，对话框消失后会停止铃声并结束活动
default:
break;
}
}
+ /**
+ * 对话框消失时触发：停止铃声并结束活动
+ * @param dialog 对话框实例
+ */
public void onDismiss(DialogInterface dialog) {
stopAlarmSound();
finish();
}
+ /**
+ * 停止闹钟铃声并释放媒体播放器资源
+ */
private void stopAlarmSound() {
if (mPlayer != null) {
- mPlayer.stop();
- mPlayer.release();
+ mPlayer.stop(); // 停止播放
+ mPlayer.release(); // 释放资源
mPlayer = null;
}
}
-}
+}
\ No newline at end of file
diff --git a/src/ui/AlarmInitReceiver.java b/src/ui/AlarmInitReceiver.java
index f221202..919d47b 100644
--- a/src/ui/AlarmInitReceiver.java
+++ b/src/ui/AlarmInitReceiver.java
@@ -27,39 +27,74 @@ 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;
+ // 字段索引常量，用于快速访问Cursor中的数据
+ private static final int COLUMN_ID = 0; // 便签ID在投影中的索引
+ private static final int COLUMN_ALERTED_DATE = 1; // 提醒时间在投影中的索引
+ /**
+ * 接收广播时触发的回调方法
+ * 负责查询所有未过期的便签提醒，并重新注册到AlarmManager
+ * @param context 上下文对象
+ * @param intent 接收到的广播意图
+ */
@Override
public void onReceive(Context context, Intent intent) {
+ // 获取当前系统时间，用于筛选未过期的提醒
long currentDate = System.currentTimeMillis();
- Cursor c = context.getContentResolver().query(Notes.CONTENT_NOTE_URI,
- PROJECTION,
+
+ // 查询数据库中所有未过期的便签提醒
+ // 条件：提醒时间 > 当前时间 且 便签类型为普通便签（TYPE_NOTE）
+ Cursor c = context.getContentResolver().query(
+ Notes.CONTENT_NOTE_URI, // 查询的内容URI（指向便签表）
+ PROJECTION, // 需要查询的字段
NoteColumns.ALERTED_DATE + ">? AND " + NoteColumns.TYPE + "=" + Notes.TYPE_NOTE,
- new String[] { String.valueOf(currentDate) },
- null);
+ new String[] { String.valueOf(currentDate) }, // 筛选条件参数（当前时间）
+ null // 排序方式（无需排序）
+ );
if (c != null) {
+ // 遍历查询结果，为每个未过期的提醒注册闹钟
if (c.moveToFirst()) {
do {
+ // 获取便签的提醒时间
long alertDate = c.getLong(COLUMN_ALERTED_DATE);
+ // 创建触发提醒时的意图（指向AlarmReceiver）
Intent sender = new Intent(context, AlarmReceiver.class);
- sender.setData(ContentUris.withAppendedId(Notes.CONTENT_NOTE_URI, c.getLong(COLUMN_ID)));
- PendingIntent pendingIntent = PendingIntent.getBroadcast(context, 0, sender, 0);
+ // 为意图附加便签ID，便于后续定位具体便签
+ sender.setData(ContentUris.withAppendedId(Notes.CONTENT_NOTE_URI,
+ c.getLong(COLUMN_ID)));
+
+ // 创建延迟执行的PendingIntent（用于触发提醒）
+ PendingIntent pendingIntent = PendingIntent.getBroadcast(
+ context, 0, sender, 0);
+
+ // 获取AlarmManager服务，用于设置系统闹钟
AlarmManager alermManager = (AlarmManager) context
.getSystemService(Context.ALARM_SERVICE);
+
+ // 注册闹钟：在指定时间（alertDate）唤醒设备并发送广播
+ // RTC_WAKEUP模式确保在设备休眠时也能触发
alermManager.set(AlarmManager.RTC_WAKEUP, alertDate, pendingIntent);
- } while (c.moveToNext());
+ } while (c.moveToNext()); // 继续处理下一个便签
}
+ // 关闭Cursor，释放资源
c.close();
}
}
-}
+}
\ No newline at end of file
diff --git a/src/ui/AlarmReceiver.java b/src/ui/AlarmReceiver.java
index 54e503b..722b750 100644
--- a/src/ui/AlarmReceiver.java
+++ b/src/ui/AlarmReceiver.java
@@ -20,11 +20,27 @@ import android.content.BroadcastReceiver;
import android.content.Context;
import android.content.Intent;
+/**
+ * 便签提醒广播接收器，负责接收系统闹钟触发的广播，并启动提醒展示界面
+ * 是小米便签提醒流程中连接闹钟触发与提醒展示的中间组件
+ */
public class AlarmReceiver extends BroadcastReceiver {
+ /**
+ * 接收广播时触发的回调方法
+ * @param context 上下文环境，用于启动Activity
+ * @param intent 接收到的意图，包含触发提醒的便签信息（如便签ID）
+ */
@Override
public void onReceive(Context context, Intent intent) {
+ // 将意图的目标组件设置为AlarmAlertActivity（便签提醒展示界面）
+ // 确保广播中携带的便签信息（如Data中的便签ID）被传递给目标界面
intent.setClass(context, AlarmAlertActivity.class);
+
+ // 添加FLAG_ACTIVITY_NEW_TASK标志：在BroadcastReceiver中启动Activity必须设置此标志
+ // 因为BroadcastReceiver本身没有任务栈，需要为启动的Activity创建新任务栈
intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
+
+ // 启动AlarmAlertActivity，展示便签提醒对话框并播放铃声
context.startActivity(intent);
}
-}
+}
\ No newline at end of file
diff --git a/src/ui/DateTimePicker.java b/src/ui/DateTimePicker.java
index 496b0cd..906261f 100644
--- a/src/ui/DateTimePicker.java
+++ b/src/ui/DateTimePicker.java
@@ -28,57 +28,75 @@ import android.view.View;
import android.widget.FrameLayout;
import android.widget.NumberPicker;
+/**
+ * 日期时间选择器组件
+ * 用于小米便签中设置提醒时间，支持日期、小时、分钟的选择，以及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 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; // 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; // 上下午选择器最小值
+ 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; // 上下午选择器（12小时制用）
+ 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 boolean mIsAm; // 是否为上午（12小时制）
+ 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();
}
};
+ /**
+ * 小时选择器值变化监听器
+ * 处理小时变更逻辑，包括跨天情况（如23点到0点）和12/24小时制转换
+ */
private NumberPicker.OnValueChangeListener mOnHourChangedListener = new NumberPicker.OnValueChangeListener() {
@Override
public void onValueChange(NumberPicker picker, int oldVal, int newVal) {
boolean isDateChanged = false;
Calendar cal = Calendar.getInstance();
+
if (!mIs24HourView) {
+ // 12小时制处理：跨天情况（如11PM到12AM需加一天，12AM到11PM需减一天）
if (!mIsAm && oldVal == HOURS_IN_HALF_DAY - 1 && newVal == HOURS_IN_HALF_DAY) {
cal.setTimeInMillis(mDate.getTimeInMillis());
cal.add(Calendar.DAY_OF_YEAR, 1);
@@ -88,12 +106,14 @@ public class DateTimePicker extends FrameLayout {
cal.add(Calendar.DAY_OF_YEAR, -1);
isDateChanged = true;
}
+ // 12点和11点切换时，切换上下午状态
if (oldVal == HOURS_IN_HALF_DAY - 1 && newVal == HOURS_IN_HALF_DAY ||
oldVal == HOURS_IN_HALF_DAY && newVal == HOURS_IN_HALF_DAY - 1) {
mIsAm = !mIsAm;
updateAmPmControl();
}
} else {
+ // 24小时制处理：跨天情况（如23点到0点加一天，0点到23点减一天）
if (oldVal == HOURS_IN_ALL_DAY - 1 && newVal == 0) {
cal.setTimeInMillis(mDate.getTimeInMillis());
cal.add(Calendar.DAY_OF_YEAR, 1);
@@ -104,9 +124,13 @@ public class DateTimePicker extends FrameLayout {
isDateChanged = true;
}
}
+
+ // 更新小时并触发事件
int newHour = mHourSpinner.getValue() % HOURS_IN_HALF_DAY + (mIsAm ? 0 : HOURS_IN_HALF_DAY);
mDate.set(Calendar.HOUR_OF_DAY, newHour);
onDateTimeChanged();
+
+ // 若日期变更，同步更新年月日
if (isDateChanged) {
setCurrentYear(cal.get(Calendar.YEAR));
setCurrentMonth(cal.get(Calendar.MONTH));
@@ -115,39 +139,55 @@ public class DateTimePicker extends FrameLayout {
}
};
+ /**
+ * 分钟选择器值变化监听器
+ * 处理分钟变更逻辑，包括跨小时情况（如59分到0分需加1小时）
+ */
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;
+
+ // 判断是否跨小时（59->0加1小时，0->59减1小时）
if (oldVal == maxValue && newVal == minValue) {
offset += 1;
} else if (oldVal == minValue && newVal == maxValue) {
offset -= 1;
}
+
if (offset != 0) {
+ // 调整小时并更新相关控件
mDate.add(Calendar.HOUR_OF_DAY, offset);
mHourSpinner.setValue(getCurrentHour());
updateDateControl();
+
+ // 更新上下午状态（12小时制）
int newHour = getCurrentHourOfDay();
if (newHour >= HOURS_IN_HALF_DAY) {
mIsAm = false;
- updateAmPmControl();
} else {
mIsAm = true;
- updateAmPmControl();
}
+ updateAmPmControl();
}
+
+ // 更新分钟并触发事件
mDate.set(Calendar.MINUTE, newVal);
onDateTimeChanged();
}
};
+ /**
+ * 上下午选择器值变化监听器
+ * 切换上午/下午状态，并调整小时（加减12小时）
+ */
private NumberPicker.OnValueChangeListener mOnAmPmChangedListener = new NumberPicker.OnValueChangeListener() {
@Override
public void onValueChange(NumberPicker picker, int oldVal, int newVal) {
mIsAm = !mIsAm;
+ // 切换上下午时调整小时（上午转下午加12小时，反之减12小时）
if (mIsAm) {
mDate.add(Calendar.HOUR_OF_DAY, -HOURS_IN_HALF_DAY);
} else {
@@ -158,39 +198,65 @@ public class DateTimePicker extends FrameLayout {
}
};
+ /**
+ * 日期时间变更监听器接口
+ * 当用户修改日期或时间时回调
+ */
public interface OnDateTimeChangedListener {
void onDateTimeChanged(DateTimePicker view, int year, int month,
- int dayOfMonth, int hourOfDay, int minute);
+ int dayOfMonth, int hourOfDay, int minute);
}
+ /**
+ * 构造方法：使用当前时间初始化，默认使用系统时间格式（12/24小时制）
+ * @param context 上下文
+ */
public DateTimePicker(Context context) {
this(context, System.currentTimeMillis());
}
+ /**
+ * 构造方法：使用指定时间初始化，默认使用系统时间格式（12/24小时制）
+ * @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;
+ 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);
+ // 初始化上下午选择器（使用系统本地化的AM/PM文本）
String[] stringsForAmPm = new DateFormatSymbols().getAmPmStrings();
mAmPmSpinner = (NumberPicker) findViewById(R.id.amPm);
mAmPmSpinner.setMinValue(AMPM_SPINNER_MIN_VAL);
@@ -198,22 +264,28 @@ public class DateTimePicker extends FrameLayout {
mAmPmSpinner.setDisplayedValues(stringsForAmPm);
mAmPmSpinner.setOnValueChangedListener(mOnAmPmChangedListener);
- // update controls to initial state
+ // 更新控件到初始状态
updateDateControl();
updateHourControl();
updateAmPmControl();
+ // 设置时间格式（12/24小时制）
set24HourView(is24HourView);
- // set to current time
+ // 设置初始时间
setCurrentDate(date);
+ // 设置启用状态
setEnabled(isEnabled());
- // set the content descriptions
+ // 初始化完成
mInitialising = false;
}
+ /**
+ * 设置组件启用状态
+ * @param enabled 是否启用
+ */
@Override
public void setEnabled(boolean enabled) {
if (mIsEnabled == enabled) {
@@ -227,24 +299,26 @@ public class DateTimePicker extends FrameLayout {
mIsEnabled = enabled;
}
+ /**
+ * 获取组件启用状态
+ * @return 是否启用
+ */
@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();
@@ -254,16 +328,15 @@ public class DateTimePicker extends FrameLayout {
}
/**
- * 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 日
+ * @param hourOfDay 时（24小时制，0-23）
+ * @param minute 分
*/
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,18 +345,16 @@ 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()) {
@@ -295,18 +366,16 @@ public class DateTimePicker extends FrameLayout {
}
/**
- * Get current month in the year
- *
- * @return The current month in the year
+ * 获取当前月份（0-11）
+ * @return 月份
*/
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 +387,16 @@ public class DateTimePicker extends FrameLayout {
}
/**
- * Get current day of the month
- *
- * @return The day of the month
+ * 获取当前日
+ * @return 日
*/
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 日
*/
public void setCurrentDay(int dayOfMonth) {
if (!mInitialising && dayOfMonth == getCurrentDay()) {
@@ -341,18 +408,23 @@ 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小时制，0-23）
+ * @return 小时
*/
public int getCurrentHourOfDay() {
return mDate.get(Calendar.HOUR_OF_DAY);
}
+ /**
+ * 根据当前时间格式（12/24小时制）获取小时显示值
+ * @return 小时显示值
+ */
private int getCurrentHour() {
if (mIs24HourView){
return getCurrentHourOfDay();
} else {
int hour = getCurrentHourOfDay();
+ // 12小时制转换：13->1，0->12
if (hour > HOURS_IN_HALF_DAY) {
return hour - HOURS_IN_HALF_DAY;
} else {
@@ -362,16 +434,17 @@ public class DateTimePicker extends FrameLayout {
}
/**
- * 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);
+
if (!mIs24HourView) {
+ // 12小时制处理：更新上下午状态和小时显示值
if (hourOfDay >= HOURS_IN_HALF_DAY) {
mIsAm = false;
if (hourOfDay > HOURS_IN_HALF_DAY) {
@@ -385,21 +458,22 @@ public class DateTimePicker extends FrameLayout {
}
updateAmPmControl();
}
+
mHourSpinner.setValue(hourOfDay);
onDateTimeChanged();
}
/**
- * Get currentMinute
- *
- * @return The Current Minute
+ * 获取当前分钟
+ * @return 分钟
*/
public int getCurrentMinute() {
return mDate.get(Calendar.MINUTE);
}
/**
- * Set current minute
+ * 设置当前分钟
+ * @param minute 分钟（0-59）
*/
public void setCurrentMinute(int minute) {
if (!mInitialising && minute == getCurrentMinute()) {
@@ -411,22 +485,23 @@ public class DateTimePicker extends FrameLayout {
}
/**
- * @return true if this is in 24 hour view else false.
+ * 判断是否为24小时制显示
+ * @return 是否为24小时制
*/
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.
+ * 设置时间显示格式（24小时制/12小时制）
+ * @param is24HourView true为24小时制，false为12小时制
*/
public void set24HourView(boolean is24HourView) {
if (mIs24HourView == is24HourView) {
return;
}
mIs24HourView = is24HourView;
+ // 24小时制隐藏上下午选择器，12小时制显示
mAmPmSpinner.setVisibility(is24HourView ? View.GONE : View.VISIBLE);
int hour = getCurrentHourOfDay();
updateHourControl();
@@ -434,20 +509,30 @@ public class DateTimePicker extends FrameLayout {
updateAmPmControl();
}
+ /**
+ * 更新日期选择器显示内容（近一周的日期，格式：月.日 星期）
+ */
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);
+
+ // 生成近一周的日期文本
for (int i = 0; i < DAYS_IN_ALL_WEEK; ++i) {
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.setValue(DAYS_IN_ALL_WEEK / 2); // 默认选中当前日期
mDateSpinner.invalidate();
}
+ /**
+ * 更新上下午选择器状态（根据12小时制和当前上下午状态）
+ */
private void updateAmPmControl() {
if (mIs24HourView) {
mAmPmSpinner.setVisibility(View.GONE);
@@ -458,6 +543,9 @@ public class DateTimePicker extends FrameLayout {
}
}
+ /**
+ * 更新小时选择器的范围（根据12/24小时制）
+ */
private void updateHourControl() {
if (mIs24HourView) {
mHourSpinner.setMinValue(HOUR_SPINNER_MIN_VAL_24_HOUR_VIEW);
@@ -469,17 +557,20 @@ public class DateTimePicker extends FrameLayout {
}
/**
- * 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/ui/DateTimePickerDialog.java b/src/ui/DateTimePickerDialog.java
index 2c47ba4..309d989 100644
--- a/src/ui/DateTimePickerDialog.java
+++ b/src/ui/DateTimePickerDialog.java
@@ -29,60 +29,107 @@ import android.content.DialogInterface.OnClickListener;
import android.text.format.DateFormat;
import android.text.format.DateUtils;
+/**
+ * 日期时间选择对话框，用于小米便签中设置提醒时间的交互界面
+ * 继承自AlertDialog，内部集成DateTimePicker作为选择视图，提供日期和时间的可视化选择
+ */
public class DateTimePickerDialog extends AlertDialog implements OnClickListener {
+ // 用于维护当前选中的日期时间
private Calendar mDate = Calendar.getInstance();
+ // 是否采用24小时制显示时间
private boolean mIs24HourView;
+ // 日期时间选择完成后的回调监听器（由调用者实现，如NoteEditActivity）
private OnDateTimeSetListener mOnDateTimeSetListener;
+ // 自定义的日期时间选择器视图，负责用户选择交互
private DateTimePicker mDateTimePicker;
+ /**
+ * 日期时间选择完成的回调接口
+ * 当用户点击"确定"后，通过此接口将选中的时间（毫秒级时间戳）传递给调用者
+ */
public interface OnDateTimeSetListener {
void OnDateTimeSet(AlertDialog dialog, long date);
}
+ /**
+ * 构造方法：初始化日期时间选择对话框
+ * @param context 上下文环境（如NoteEditActivity）
+ * @param date 初始日期时间（毫秒级时间戳，通常为当前时间或便签已有的提醒时间）
+ */
public DateTimePickerDialog(Context context, long date) {
super(context);
+ // 初始化自定义的日期时间选择器
mDateTimePicker = new DateTimePicker(context);
+ // 将选择器设置为对话框的内容视图
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) {
+ // 更新内部维护的日期时间
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);
mDateTimePicker.setCurrentDate(mDate.getTimeInMillis());
+
+ // 设置对话框按钮："确定"按钮触发onClick方法，"取消"按钮不执行操作
setButton(context.getString(R.string.datetime_dialog_ok), this);
setButton2(context.getString(R.string.datetime_dialog_cancel), (OnClickListener)null);
+
+ // 根据系统设置初始化24小时制显示模式
set24HourView(DateFormat.is24HourFormat(this.getContext()));
+ // 初始化对话框标题为初始日期时间
updateTitle(mDate.getTimeInMillis());
}
+ /**
+ * 设置时间显示模式（24小时制/12小时制）
+ * @param is24HourView true为24小时制，false为12小时制
+ */
public void set24HourView(boolean is24HourView) {
mIs24HourView = is24HourView;
}
+ /**
+ * 设置日期时间选择完成后的回调监听器
+ * @param callBack 实现了OnDateTimeSetListener的对象（通常为调用对话框的Activity）
+ */
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;
- flag |= mIs24HourView ? DateUtils.FORMAT_24HOUR : DateUtils.FORMAT_24HOUR;
+ // 定义日期时间的显示格式：包含年、月、日、时间
+ int flag = DateUtils.FORMAT_SHOW_YEAR | DateUtils.FORMAT_SHOW_DATE | DateUtils.FORMAT_SHOW_TIME;
+ // 根据24小时制模式调整显示格式
+ flag |= mIs24HourView ? DateUtils.FORMAT_24HOUR : DateUtils.FORMAT_12HOUR;
+ // 格式化时间并设置为对话框标题
setTitle(DateUtils.formatDateTime(this.getContext(), date, flag));
}
+ /**
+ * 处理"确定"按钮的点击事件
+ * 当用户点击确定后，通过回调接口将选中的时间传递给调用者
+ */
public void onClick(DialogInterface arg0, int arg1) {
if (mOnDateTimeSetListener != null) {
+ // 回调传递选中的时间（毫秒级时间戳）
mOnDateTimeSetListener.OnDateTimeSet(this, mDate.getTimeInMillis());
}
}
diff --git a/src/ui/DropdownMenu.java b/src/ui/DropdownMenu.java
index 613dc74..041b5f6 100644
--- a/src/ui/DropdownMenu.java
+++ b/src/ui/DropdownMenu.java
@@ -27,17 +27,35 @@ import android.widget.PopupMenu.OnMenuItemClickListener;
import net.micode.notes.R;
+/**
+ * 下拉菜单工具类，用于在小米便签中实现按钮触发的弹出式菜单
+ * 典型场景：笔记列表的批量操作菜单、编辑页的功能选项菜单等
+ */
public class DropdownMenu {
+ // 触发下拉菜单的按钮
private Button mButton;
+ // 系统提供的弹出式菜单组件，负责显示下拉选项
private PopupMenu mPopupMenu;
+ // 菜单容器，存储从资源文件加载的菜单项
private Menu mMenu;
+ /**
+ * 构造方法：初始化下拉菜单
+ * @param context 上下文对象，用于访问资源和创建视图
+ * @param button 触发下拉菜单的按钮
+ * @param menuId 菜单资源ID（定义在res/menu目录下）
+ */
public DropdownMenu(Context context, Button button, int menuId) {
mButton = button;
+ // 设置按钮背景为下拉图标（箭头图标）
mButton.setBackgroundResource(R.drawable.dropdown_icon);
+ // 初始化PopupMenu，绑定到触发按钮
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 +63,30 @@ public class DropdownMenu {
});
}
+ /**
+ * 设置下拉菜单项的点击事件监听器
+ * @param listener 监听器对象，处理菜单项点击逻辑
+ */
public void setOnDropdownMenuItemClickListener(OnMenuItemClickListener listener) {
if (mPopupMenu != null) {
mPopupMenu.setOnMenuItemClickListener(listener);
}
}
+ /**
+ * 根据ID查找菜单中的具体选项
+ * @param id 菜单项的资源ID
+ * @return 对应的MenuItem对象，可用于修改状态（如勾选、隐藏）
+ */
public MenuItem findItem(int id) {
return mMenu.findItem(id);
}
+ /**
+ * 设置触发按钮的显示文本
+ * @param title 要显示的文本（如"已选择3项"）
+ */
public void setTitle(CharSequence title) {
mButton.setText(title);
}
-}
+}
\ No newline at end of file
diff --git a/src/ui/FoldersListAdapter.java b/src/ui/FoldersListAdapter.java
index 96b77da..6fee552 100644
--- a/src/ui/FoldersListAdapter.java
+++ b/src/ui/FoldersListAdapter.java
@@ -28,53 +28,103 @@ import net.micode.notes.R;
import net.micode.notes.data.Notes;
import net.micode.notes.data.Notes.NoteColumns;
-
+/**
+ * 文件夹列表适配器，用于小米便签中展示文件夹列表（如移动便签时选择目标文件夹）
+ * 继承自CursorAdapter，负责将数据库中的文件夹数据与列表视图绑定
+ */
public class FoldersListAdapter extends CursorAdapter {
+ /**
+ * 数据库查询投影：指定需要查询的文件夹字段
+ * 包含文件夹ID（用于区分不同文件夹）和文件夹名称（存储在SNIPPET字段）
+ */
public static final String [] PROJECTION = {
- NoteColumns.ID,
- NoteColumns.SNIPPET
+ NoteColumns.ID, // 文件夹ID
+ NoteColumns.SNIPPET // 文件夹名称（小米便签中文件夹名称存储在此字段）
};
- public static final int ID_COLUMN = 0;
- public static final int NAME_COLUMN = 1;
+ /**
+ * 投影字段对应的索引，用于从Cursor中快速获取数据
+ */
+ public static final int ID_COLUMN = 0; // PROJECTION中ID字段的索引
+ public static final int NAME_COLUMN = 1; // PROJECTION中SNIPPET（名称）字段的索引
+ /**
+ * 构造方法：初始化文件夹列表适配器
+ * @param context 上下文环境（如调用文件夹列表的Activity或对话框）
+ * @param c 包含文件夹数据的数据库游标（查询结果）
+ */
public FoldersListAdapter(Context context, Cursor c) {
super(context, c);
// TODO Auto-generated constructor stub
}
+ /**
+ * 创建新的列表项视图
+ * @param context 上下文环境
+ * @param cursor 包含当前项数据的游标（此处未直接使用，仅用于创建视图）
+ * @param parent 父视图容器（通常为ListView）
+ * @return 自定义的文件夹列表项视图（FolderListItem实例）
+ */
@Override
public View newView(Context context, Cursor cursor, ViewGroup parent) {
return new FolderListItem(context);
}
+ /**
+ * 将游标中的文件夹数据绑定到列表项视图
+ * @param view 列表项视图（FolderListItem实例）
+ * @param context 上下文环境
+ * @param cursor 包含当前文件夹数据的游标
+ */
@Override
public void bindView(View view, Context context, Cursor cursor) {
if (view instanceof FolderListItem) {
+ // 处理根文件夹的特殊名称：根文件夹ID为Notes.ID_ROOT_FOLDER，显示为“移动到父文件夹”
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);
+ // 根文件夹特殊处理，其他文件夹直接取SNIPPET字段值
return (cursor.getLong(ID_COLUMN) == Notes.ID_ROOT_FOLDER) ? context
.getString(R.string.menu_move_parent_folder) : cursor.getString(NAME_COLUMN);
}
+ /**
+ * 自定义文件夹列表项视图，继承LinearLayout，用于展示单个文件夹的名称
+ */
private class FolderListItem extends LinearLayout {
- private TextView mName;
+ private TextView mName; // 用于显示文件夹名称的文本控件
+ /**
+ * 构造方法：初始化列表项布局和控件
+ * @param context 上下文环境
+ */
public FolderListItem(Context context) {
super(context);
+ // 加载文件夹列表项的布局文件（folder_list_item.xml）
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/ui/NoteEditActivity.java b/src/ui/NoteEditActivity.java
index 96a9ff8..e42e69c 100644
--- a/src/ui/NoteEditActivity.java
+++ b/src/ui/NoteEditActivity.java
@@ -1,19 +1,3 @@
-/*
- * Copyright (c) 2010-2011, The MiCode Open Source Community (www.micode.net)
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
package net.micode.notes.ui;
import android.app.Activity;
@@ -72,18 +56,27 @@ 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;
+ /**
+ * 头部视图持有者类，用于缓存头部视图中的控件，优化性能
+ */
+ private class HeadViewHolder {
+ public TextView tvModified; // 显示笔记修改时间的文本视图
+ public ImageView ivAlertIcon; // 提醒图标
+ public TextView tvAlertDate; // 显示提醒日期的文本视图
+ public ImageView ibSetBgColor; // 设置背景颜色的按钮
}
+ /**
+ * 背景颜色选择按钮映射表
+ * 键：按钮资源ID，值：对应的背景颜色资源ID（来自ResourceParser）
+ */
private static final Map sBgSelectorBtnsMap = new HashMap();
static {
sBgSelectorBtnsMap.put(R.id.iv_bg_yellow, ResourceParser.YELLOW);
@@ -93,6 +86,10 @@ public class NoteEditActivity extends Activity implements OnClickListener,
sBgSelectorBtnsMap.put(R.id.iv_bg_white, ResourceParser.WHITE);
}
+ /**
+ * 背景颜色选择状态映射表
+ * 键：背景颜色资源ID（来自ResourceParser），值：对应的选中状态图标资源ID
+ */
private static final Map sBgSelectorSelectionMap = new HashMap();
static {
sBgSelectorSelectionMap.put(ResourceParser.YELLOW, R.id.iv_bg_yellow_select);
@@ -102,6 +99,10 @@ public class NoteEditActivity extends Activity implements OnClickListener,
sBgSelectorSelectionMap.put(ResourceParser.WHITE, R.id.iv_bg_white_select);
}
+ /**
+ * 字体大小选择按钮映射表
+ * 键：按钮资源ID，值：对应的字体大小资源ID（来自ResourceParser）
+ */
private static final Map sFontSizeBtnsMap = new HashMap();
static {
sFontSizeBtnsMap.put(R.id.ll_font_large, ResourceParser.TEXT_LARGE);
@@ -110,6 +111,10 @@ public class NoteEditActivity extends Activity implements OnClickListener,
sFontSizeBtnsMap.put(R.id.ll_font_super, ResourceParser.TEXT_SUPER);
}
+ /**
+ * 字体大小选择状态映射表
+ * 键：字体大小资源ID（来自ResourceParser），值：对应的选中状态图标资源ID
+ */
private static final Map sFontSelectorSelectionMap = new HashMap();
static {
sFontSelectorSelectionMap.put(ResourceParser.TEXT_LARGE, R.id.iv_large_select);
@@ -118,59 +123,66 @@ public class NoteEditActivity extends Activity implements OnClickListener,
sFontSelectorSelectionMap.put(ResourceParser.TEXT_SUPER, R.id.iv_super_select);
}
- private static final String TAG = "NoteEditActivity";
+ private static final String TAG = "NoteEditActivity"; // 日志标签
- private HeadViewHolder mNoteHeaderHolder;
+ private HeadViewHolder mNoteHeaderHolder; // 头部视图持有者实例
- private View mHeadViewPanel;
+ private View mHeadViewPanel; // 头部视图面板
- private View mNoteBgColorSelector;
+ private View mNoteBgColorSelector; // 背景颜色选择器视图
- private View mFontSizeSelector;
+ private View mFontSizeSelector; // 字体大小选择器视图
- private EditText mNoteEditor;
+ private EditText mNoteEditor; // 笔记编辑文本框
- private View mNoteEditorPanel;
+ private View mNoteEditorPanel; // 笔记编辑面板
- private WorkingNote mWorkingNote;
+ private WorkingNote mWorkingNote; // 当前正在编辑的笔记对象
- private SharedPreferences mSharedPrefs;
- private int mFontSizeId;
+ 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 LinearLayout mEditTextList; // 列表模式下的编辑框列表
- private String mUserQuery;
- private Pattern mPattern;
+ private String mUserQuery; // 用户查询文本（用于搜索高亮）
+ private Pattern mPattern; // 正则表达式模式（用于查询文本高亮）
+ /**
+ * 活动创建时调用的方法
+ * 初始化布局和活动状态
+ */
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
- this.setContentView(R.layout.note_edit);
+ 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);
+ // 如果保存的状态中包含笔记ID，则恢复对应的笔记
if (savedInstanceState != null && savedInstanceState.containsKey(Intent.EXTRA_UID)) {
Intent intent = new Intent(Intent.ACTION_VIEW);
intent.putExtra(Intent.EXTRA_UID, savedInstanceState.getLong(Intent.EXTRA_UID));
+ // 如果恢复状态失败，则结束活动
if (!initActivityState(intent)) {
finish();
return;
@@ -179,24 +191,31 @@ public class NoteEditActivity extends Activity implements OnClickListener,
}
}
+ /**
+ * 初始化活动状态，根据传入的意图处理笔记的加载或创建
+ * @param intent 传入的意图，包含操作类型和相关数据
+ * @return 初始化成功返回true，否则返回false
+ */
private boolean initActivityState(Intent intent) {
/**
- * If the user specified the {@link Intent#ACTION_VIEW} but not provided with id,
- * then jump to the NotesListActivity
+ * 如果用户指定了查看操作（ACTION_VIEW）但未提供笔记ID，
+ * 则跳转到笔记列表活动
*/
mWorkingNote = null;
+ // 处理查看已有笔记的操作
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 +223,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 +231,14 @@ 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
+ }
+ // 处理创建或编辑新笔记的操作
+ else if(TextUtils.equals(Intent.ACTION_INSERT_OR_EDIT, intent.getAction())) {
+ // 新笔记
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 +247,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 +255,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 +265,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);
@@ -258,73 +285,100 @@ public class NoteEditActivity extends Activity implements OnClickListener,
finish();
return false;
}
+ // 设置笔记设置变化监听器
mWorkingNote.setOnSettingStatusChangedListener(this);
return true;
}
+ /**
+ * 活动恢复时调用的方法
+ * 初始化笔记显示界面
+ */
@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
+ * TODO: 添加设置提醒的菜单。目前禁用，因为DateTimePicker尚未准备好
*/
- showAlertHeader();
+ showAlertHeader(); // 显示提醒信息
}
+ /**
+ * 显示提醒头部信息
+ * 根据提醒时间是否过期显示不同内容
+ */
private void showAlertHeader() {
if (mWorkingNote.hasClockAlert()) {
long time = System.currentTimeMillis();
if (time > mWorkingNote.getAlertDate()) {
- mNoteHeaderHolder.tvAlertDate.setText(R.string.note_alert_expired);
+ mNoteHeaderHolder.tvAlertDate.setText(R.string.note_alert_expired); // 提醒已过期
} else {
+ // 显示相对时间（如"30分钟后"）
mNoteHeaderHolder.tvAlertDate.setText(DateUtils.getRelativeTimeSpanString(
mWorkingNote.getAlertDate(), time, DateUtils.MINUTE_IN_MILLIS));
}
mNoteHeaderHolder.tvAlertDate.setVisibility(View.VISIBLE);
mNoteHeaderHolder.ivAlertIcon.setVisibility(View.VISIBLE);
} else {
+ // 没有提醒时隐藏相关视图
mNoteHeaderHolder.tvAlertDate.setVisibility(View.GONE);
mNoteHeaderHolder.ivAlertIcon.setVisibility(View.GONE);
};
}
+ /**
+ * 当活动收到新的意图时调用
+ * 重新初始化活动状态
+ */
@Override
protected void onNewIntent(Intent intent) {
super.onNewIntent(intent);
initActivityState(intent);
}
+ /**
+ * 当活动状态需要保存时调用
+ * 保存当前正在编辑的笔记ID
+ */
@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的新笔记，应先保存以生成ID。
+ * 如果编辑的笔记不值得保存，则没有ID，相当于创建新笔记
*/
if (!mWorkingNote.existInDatabase()) {
saveNote();
@@ -333,14 +387,20 @@ 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
&& !inRangeOfView(mNoteBgColorSelector, ev)) {
mNoteBgColorSelector.setVisibility(View.GONE);
return true;
}
+ // 如果字体大小选择器可见且触摸点不在其范围内，则隐藏它
if (mFontSizeSelector.getVisibility() == View.VISIBLE
&& !inRangeOfView(mFontSizeSelector, ev)) {
mFontSizeSelector.setVisibility(View.GONE);
@@ -349,65 +409,99 @@ public class NoteEditActivity extends Activity implements OnClickListener,
return super.dispatchTouchEvent(ev);
}
+ /**
+ * 判断触摸事件是否在指定视图范围内
+ * @param view 目标视图
+ * @param ev 触摸事件
+ * @return 触摸点在视图范围内返回true，否则返回false
+ */
private boolean inRangeOfView(View view, MotionEvent ev) {
int []location = new int[2];
- view.getLocationOnScreen(location);
+ view.getLocationOnScreen(location); // 获取视图在屏幕上的位置
int x = location[0];
int y = location[1];
+ // 判断触摸点是否在视图的边界内
if (ev.getX() < x
|| 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();
- mNoteHeaderHolder.tvModified = (TextView) findViewById(R.id.tv_modified_date);
- mNoteHeaderHolder.ivAlertIcon = (ImageView) findViewById(R.id.iv_alert_icon);
- mNoteHeaderHolder.tvAlertDate = (TextView) findViewById(R.id.tv_alert_date);
- mNoteHeaderHolder.ibSetBgColor = (ImageView) findViewById(R.id.btn_set_bg_color);
- mNoteHeaderHolder.ibSetBgColor.setOnClickListener(this);
+ mNoteHeaderHolder.tvModified = (TextView) findViewById(R.id.tv_modified_date); // 最后修改时间文本
+ mNoteHeaderHolder.ivAlertIcon = (ImageView) findViewById(R.id.iv_alert_icon); // 提醒图标
+ mNoteHeaderHolder.tvAlertDate = (TextView) findViewById(R.id.tv_alert_date); // 提醒日期文本
+ mNoteHeaderHolder.ibSetBgColor = (ImageView) findViewById(R.id.btn_set_bg_color); // 设置背景颜色按钮
+ mNoteHeaderHolder.ibSetBgColor.setOnClickListener(this); // 绑定点击事件
+
+ // 获取笔记编辑器和其容器
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);
};
+
+ // 获取SharedPreferences用于存储字体大小设置
mSharedPrefs = PreferenceManager.getDefaultSharedPreferences(this);
+ // 从SharedPreferences读取保存的字体大小ID，默认使用默认字体大小
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}
+ * 修复SharedPreferences中存储的资源ID可能超出资源长度的问题
+ * 若超出则使用默认字体大小
*/
if(mFontSizeId >= TextAppearanceResources.getResourcesSize()) {
mFontSizeId = ResourceParser.BG_DEFAULT_FONT_SIZE;
}
+
+ // 获取清单模式下的编辑框列表容器
mEditTextList = (LinearLayout) findViewById(R.id.note_edit_list);
}
+ /**
+ * 活动暂停时调用
+ * 保存当前笔记内容并清除设置面板状态
+ */
@Override
protected void onPause() {
super.onPause();
+ // 保存笔记并打印日志
if(saveNote()) {
Log.d(TAG, "Note data was saved with length:" + mWorkingNote.getContent().length());
}
+ // 清除设置面板（如背景选择器、字体选择器）的显示状态
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,30 +511,50 @@ 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);
}
+ /**
+ * 处理视图点击事件
+ * 包括背景颜色设置、字体大小设置等按钮的点击逻辑
+ */
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);
- } else if (sBgSelectorBtnsMap.containsKey(id)) {
+ 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);
- } else if (sFontSizeBtnsMap.containsKey(id)) {
+ }
+ // 处理字体大小选择器中的按钮点击
+ else if (sFontSizeBtnsMap.containsKey(id)) {
+ // 隐藏之前选中的字体大小指示器
findViewById(sFontSelectorSelectionMap.get(mFontSizeId)).setVisibility(View.GONE);
+ // 更新字体大小ID并保存到SharedPreferences
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());
@@ -448,20 +562,32 @@ public class NoteEditActivity extends Activity implements OnClickListener,
mNoteEditor.setTextAppearance(this,
TextAppearanceResources.getTexAppearanceResource(mFontSizeId));
}
+ // 隐藏字体大小选择器
mFontSizeSelector.setVisibility(View.GONE);
}
}
+ /**
+ * 处理返回键点击事件
+ * 优先关闭设置面板，否则保存笔记并返回
+ */
@Override
public void onBackPressed() {
+ // 若关闭了设置面板则直接返回
if(clearSettingState()) {
return;
}
+ // 保存笔记并执行默认返回操作
saveNote();
super.onBackPressed();
}
+ /**
+ * 清除设置面板的显示状态
+ * 隐藏背景颜色选择器和字体大小选择器
+ * @return 若有面板被隐藏则返回true，否则返回false
+ */
private boolean clearSettingState() {
if (mNoteBgColorSelector.getVisibility() == View.VISIBLE) {
mNoteBgColorSelector.setVisibility(View.GONE);
@@ -473,30 +599,45 @@ public class NoteEditActivity extends Activity implements OnClickListener,
return false;
}
+ /**
+ * 背景颜色改变时调用
+ * 更新背景颜色指示器和相关面板的背景资源
+ */
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();
+ // 根据笔记所在文件夹加载对应的菜单资源
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);
} else {
@@ -505,13 +646,18 @@ public class NoteEditActivity extends Activity implements OnClickListener,
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,6 +665,7 @@ 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();
}
@@ -527,24 +674,30 @@ public class NoteEditActivity extends Activity implements OnClickListener,
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,10 +706,14 @@ 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);
}
});
@@ -564,8 +721,10 @@ public class NoteEditActivity extends Activity implements OnClickListener,
}
/**
- * Share note to apps that support {@link Intent#ACTION_SEND} action
- * and {@text/plain} type
+ * 分享笔记内容到其他应用
+ * 通过ACTION_SEND意图分享纯文本内容
+ * @param context 上下文
+ * @param info 要分享的文本内容
*/
private void sendTo(Context context, String info) {
Intent intent = new Intent(Intent.ACTION_SEND);
@@ -574,11 +733,15 @@ public class NoteEditActivity extends Activity implements OnClickListener,
context.startActivity(intent);
}
+ /**
+ * 创建新笔记
+ * 先保存当前笔记，再启动新的编辑活动
+ */
private void createNewNote() {
- // Firstly, save current editing notes
+ // 保存当前编辑的笔记
saveNote();
- // For safety, start a new NoteEditActivity
+ // 安全起见，关闭当前活动并启动新的NoteEditActivity
finish();
Intent intent = new Intent(this, NoteEditActivity.class);
intent.setAction(Intent.ACTION_INSERT_OR_EDIT);
@@ -586,15 +749,21 @@ public class NoteEditActivity extends Activity implements OnClickListener,
startActivity(intent);
}
+ /**
+ * 删除当前笔记
+ * 非同步模式下直接删除，同步模式下移动到回收站
+ */
private void deleteCurrentNote() {
if (mWorkingNote.existInDatabase()) {
HashSet ids = new HashSet();
long id = mWorkingNote.getNoteId();
+ // 检查笔记ID是否有效
if (id != Notes.ID_ROOT_FOLDER) {
ids.add(id);
} else {
Log.d(TAG, "Wrong note id, should not happen");
}
+ // 根据同步模式执行不同操作
if (!isSyncMode()) {
if (!DataUtils.batchDeleteNotes(getContentResolver(), ids)) {
Log.e(TAG, "Delete Note error");
@@ -605,21 +774,32 @@ public class NoteEditActivity extends Activity implements OnClickListener,
}
}
}
+ // 标记笔记为已删除
mWorkingNote.markDeleted(true);
}
+ /**
+ * 判断是否处于同步模式
+ * @return 若设置了同步账户则返回true，否则返回false
+ */
private boolean isSyncMode() {
return NotesPreferenceActivity.getSyncAccountName(this).trim().length() > 0;
}
+ /**
+ * 提醒时间改变时调用
+ * 处理闹钟的设置或取消
+ * @param date 提醒时间戳
+ * @param set 是否设置提醒（true为设置，false为取消）
+ */
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();
}
+ // 笔记ID有效时处理闹钟
if (mWorkingNote.getNoteId() > 0) {
Intent intent = new Intent(this, AlarmReceiver.class);
intent.setData(ContentUris.withAppendedId(Notes.CONTENT_NOTE_URI, mWorkingNote.getNoteId()));
@@ -627,38 +807,51 @@ public class NoteEditActivity extends Activity implements OnClickListener,
AlarmManager alarmManager = ((AlarmManager) getSystemService(ALARM_SERVICE));
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
+ * 若用户未输入内容（笔记未保存），无有效ID，提示用户输入内容
*/
Log.e(TAG, "Clock alert setting error");
showToast(R.string.error_note_empty_for_clock);
}
}
+ /**
+ * 小部件改变时调用
+ * 触发小部件更新
+ */
public void onWidgetChanged() {
updateWidget();
}
+ /**
+ * 处理编辑框删除事件（清单模式下）
+ * @param index 要删除的编辑框索引
+ * @param text 被删除的文本内容
+ */
public void onEditTextDelete(int index, String text) {
int childCount = mEditTextList.getChildCount();
+ // 若只剩一个编辑框则不删除
if (childCount == 1) {
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);
@@ -672,48 +865,72 @@ public class NoteEditActivity extends Activity implements OnClickListener,
edit.setSelection(length);
}
+ /**
+ * 处理编辑框回车事件（清单模式下）
+ * 在当前位置插入新的编辑框
+ * @param index 当前编辑框索引
+ * @param text 编辑框中的文本内容
+ */
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);
}
}
+ /**
+ * 切换到清单模式
+ * 将普通文本按换行分割为多个清单项
+ * @param text 要转换的文本内容
+ */
private void switchToListMode(String text) {
mEditTextList.removeAllViews();
String[] items = text.split("\n");
int index = 0;
+ // 为每个非空文本项创建清单项
for (String item : items) {
if(!TextUtils.isEmpty(item)) {
mEditTextList.addView(getListItem(item, index));
index++;
}
}
+ // 添加一个空的清单项用于继续输入
mEditTextList.addView(getListItem("", index));
mEditTextList.getChildAt(index).findViewById(R.id.et_edit_text).requestFocus();
+ // 切换显示模式（隐藏普通编辑器，显示清单编辑框列表）
mNoteEditor.setVisibility(View.GONE);
mEditTextList.setVisibility(View.VISIBLE);
}
+ /**
+ * 高亮显示查询结果
+ * 对文本中与查询词匹配的部分设置背景色
+ * @param fullText 完整文本
+ * @param userQuery 用户查询词
+ * @return 处理后的带高亮效果的文本
+ */
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(
@@ -724,43 +941,70 @@ public class NoteEditActivity extends Activity implements OnClickListener,
}
return spannable;
}
-
+ /**
+ * 创建并返回列表模式下的列表项视图
+ * @param item 列表项的文本内容
+ * @param index 列表项的索引位置
+ * @return 构建好的列表项视图
+ */
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);
edit.setPaintFlags(edit.getPaintFlags() | Paint.STRIKE_THRU_TEXT_FLAG);
+ // 截取前缀后的文本内容
item = item.substring(TAG_CHECKED.length(), item.length()).trim();
} else if (item.startsWith(TAG_UNCHECKED)) {
+ // 带未选前缀：取消勾选并移除删除线
cb.setChecked(false);
edit.setPaintFlags(Paint.ANTI_ALIAS_FLAG | Paint.DEV_KERN_TEXT_FLAG);
+ // 截取前缀后的文本内容
item = item.substring(TAG_UNCHECKED.length(), item.length()).trim();
}
+ // 设置文本变化监听器
edit.setOnTextViewChangeListener(this);
+ // 设置列表项索引
edit.setIndex(index);
+ // 设置文本内容（支持查询高亮）
edit.setText(getHighlightQueryResult(item, mUserQuery));
return view;
}
+ /**
+ * 文本内容变化时回调（控制复选框显示/隐藏）
+ * @param index 列表项索引
+ * @param hasText 文本是否有内容
+ */
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,28 +1012,43 @@ public class NoteEditActivity extends Activity implements OnClickListener,
}
}
+ /**
+ * 检查列表模式切换时的处理
+ * @param oldMode 旧模式
+ * @param newMode 新模式
+ */
public void onCheckListModeChanged(int oldMode, int newMode) {
if (newMode == TextNote.MODE_CHECK_LIST) {
+ // 切换到列表模式：将普通文本转换为列表项
switchToListMode(mNoteEditor.getText().toString());
} else {
+ // 切换到普通模式：获取列表内容并转换为普通文本
if (!getWorkingText()) {
+ // 无选中项时，移除未选前缀
mWorkingNote.setWorkingText(mWorkingNote.getContent().replace(TAG_UNCHECKED + " ",
""));
}
+ // 显示普通编辑框，隐藏列表
mNoteEditor.setText(getHighlightQueryResult(mWorkingNote.getContent(), mUserQuery));
mEditTextList.setVisibility(View.GONE);
mNoteEditor.setVisibility(View.VISIBLE);
}
}
+ /**
+ * 获取当前编辑的文本内容（根据模式处理）
+ * @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;
@@ -800,74 +1059,103 @@ public class NoteEditActivity extends Activity implements OnClickListener,
}
mWorkingNote.setWorkingText(sb.toString());
} else {
+ // 普通模式：直接获取编辑框内容
mWorkingNote.setWorkingText(mNoteEditor.getText().toString());
}
return hasChecked;
}
+ /**
+ * 保存笔记内容
+ * @return 是否保存成功
+ */
private boolean saveNote() {
+ // 先获取当前编辑的内容
getWorkingText();
+ // 保存笔记
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
+ * 从列表页进入编辑页有两种模式：
+ * 1. 打开已有笔记：返回时需要定位到原位置
+ * 2. 创建新笔记：返回时需要定位到列表顶部
+ * 通过设置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();
}
+ // 笔记ID有效时创建快捷方式
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()));
+ makeShortcutIconTitle(mWorkingNote.getContent())); // 快捷方式名称
sender.putExtra(Intent.EXTRA_SHORTCUT_ICON_RESOURCE,
- Intent.ShortcutIconResource.fromContext(this, R.drawable.icon_app));
- sender.putExtra("duplicate", true);
- sender.setAction("com.android.launcher.action.INSTALL_SHORTCUT");
+ Intent.ShortcutIconResource.fromContext(this, R.drawable.icon_app)); // 快捷方式图标
+ sender.putExtra("duplicate", true); // 允许重复创建
+ sender.setAction("com.android.launcher.action.INSTALL_SHORTCUT"); // 启动器安装快捷方式动作
+
+ // 显示提示并发送广播创建快捷方式
showToast(R.string.info_note_enter_desktop);
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
+ * 处理异常情况：用户未输入内容（笔记未保存）
+ * 此时无有效笔记ID，提示用户输入内容
*/
Log.e(TAG, "Send to desktop error");
showToast(R.string.error_note_empty_for_send_to_desktop);
}
}
+ /**
+ * 生成快捷方式图标标题（处理特殊前缀并限制长度）
+ * @param content 笔记内容
+ * @return 处理后的标题
+ */
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;
}
+ /**
+ * 显示短时长提示信息
+ * @param resId 字符串资源ID
+ */
private void showToast(int resId) {
showToast(resId, Toast.LENGTH_SHORT);
}
+ /**
+ * 显示指定时长的提示信息
+ * @param resId 字符串资源ID
+ * @param duration 时长（Toast.LENGTH_SHORT/Toast.LENGTH_LONG）
+ */
private void showToast(int resId, int duration) {
Toast.makeText(this, resId, duration).show();
}
-}
+}
\ No newline at end of file
diff --git a/src/ui/NoteEditText.java b/src/ui/NoteEditText.java
index 2afe2a8..bfcb48d 100644
--- a/src/ui/NoteEditText.java
+++ b/src/ui/NoteEditText.java
@@ -37,73 +37,114 @@ import net.micode.notes.R;
import java.util.HashMap;
import java.util.Map;
+/**
+ * 小米便签的自定义文本输入控件，继承自EditText，扩展了便签编辑的核心交互功能
+ * 支持多输入框管理、链接识别与交互、精确光标定位等
+ */
public class NoteEditText extends EditText {
private static final String TAG = "NoteEditText";
+ // 当前输入框在多输入框列表中的索引（用于区分不同输入框）
private int mIndex;
+ // 记录删除键按下前的光标起始位置（用于判断是否删除当前输入框）
private int mSelectionStartBeforeDelete;
- private static final String SCHEME_TEL = "tel:" ;
- private static final String SCHEME_HTTP = "http:" ;
- private static final String SCHEME_EMAIL = "mailto:" ;
+ // 支持的链接协议常量
+ private static final String SCHEME_TEL = "tel:" ; // 电话协议（如"tel:10086"）
+ private static final String SCHEME_HTTP = "http:" ; // 网页协议（如"http://www.micode.net"）
+ private static final String SCHEME_EMAIL = "mailto:" ; // 邮件协议（如"mailto:test@micode.net"）
+ // 链接协议与对应菜单资源的映射（用于上下文菜单显示对应操作文字）
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
+ * 文本视图变化监听器，由{@link 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);
}
+ // 文本变化监听器实例（由NoteEditActivity设置）
private OnTextViewChangeListener mOnTextViewChangeListener;
+ /**
+ * 构造方法：初始化文本输入控件（仅上下文参数）
+ * @param context 上下文环境（如NoteEditActivity）
+ */
public NoteEditText(Context context) {
super(context, null);
- mIndex = 0;
+ mIndex = 0; // 默认索引为0
}
+ /**
+ * 设置当前输入框在多输入框列表中的索引
+ * @param index 输入框索引
+ */
public void setIndex(int index) {
mIndex = index;
}
+ /**
+ * 设置文本变化监听器，关联到NoteEditActivity
+ * @param listener 实现了OnTextViewChangeListener的监听器
+ */
public void setOnTextViewChangeListener(OnTextViewChangeListener listener) {
mOnTextViewChangeListener = listener;
}
+ /**
+ * 构造方法：初始化文本输入控件（上下文+属性集）
+ * @param context 上下文环境
+ * @param attrs 布局中定义的属性集合
+ */
public NoteEditText(Context context, AttributeSet attrs) {
super(context, attrs, android.R.attr.editTextStyle);
}
+ /**
+ * 构造方法：初始化文本输入控件（上下文+属性集+样式）
+ * @param context 上下文环境
+ * @param attrs 属性集合
+ * @param defStyle 默认样式
+ */
public NoteEditText(Context context, AttributeSet attrs, int defStyle) {
super(context, attrs, defStyle);
// TODO Auto-generated constructor stub
}
+ /**
+ * 处理触摸事件，精确设置光标位置（根据触摸坐标计算光标应在的文本位置）
+ * @param event 触摸事件（包含触摸坐标等信息）
+ * @return 事件是否被处理
+ */
@Override
public boolean onTouchEvent(MotionEvent event) {
switch (event.getAction()) {
case MotionEvent.ACTION_DOWN:
-
+ // 计算触摸点在文本中的实际坐标（扣除内边距并加上滚动偏移）
int x = (int) event.getX();
int y = (int) event.getY();
x -= getTotalPaddingLeft();
@@ -111,25 +152,33 @@ public class NoteEditText extends EditText {
x += getScrollX();
y += getScrollY();
+ // 根据坐标获取对应的文本行和偏移量，设置光标位置
Layout layout = getLayout();
- int line = layout.getLineForVertical(y);
- int off = layout.getOffsetForHorizontal(line, x);
- Selection.setSelection(getText(), off);
+ int line = layout.getLineForVertical(y); // 触摸点所在的文本行
+ int off = layout.getOffsetForHorizontal(line, x); // 行内的水平偏移（光标位置）
+ Selection.setSelection(getText(), off); // 设置光标
break;
}
-
return super.onTouchEvent(event);
}
+ /**
+ * 处理键盘按下事件，记录删除键按下前的光标位置
+ * @param keyCode 按键代码（如KEYCODE_DEL、KEYCODE_ENTER）
+ * @param event 键盘事件
+ * @return 事件是否被处理
+ */
@Override
public boolean onKeyDown(int keyCode, KeyEvent event) {
switch (keyCode) {
case KeyEvent.KEYCODE_ENTER:
+ // 回车键事件由onKeyUp处理，此处返回false让事件继续传递
if (mOnTextViewChangeListener != null) {
return false;
}
break;
case KeyEvent.KEYCODE_DEL:
+ // 记录删除键按下前的光标起始位置，用于判断是否需要删除输入框
mSelectionStartBeforeDelete = getSelectionStart();
break;
default:
@@ -138,11 +187,18 @@ public class NoteEditText extends EditText {
return super.onKeyDown(keyCode, event);
}
+ /**
+ * 处理键盘抬起事件，触发输入框增删逻辑
+ * @param keyCode 按键代码
+ * @param event 键盘事件
+ * @return 事件是否被处理
+ */
@Override
public boolean onKeyUp(int keyCode, KeyEvent event) {
switch(keyCode) {
case KeyEvent.KEYCODE_DEL:
if (mOnTextViewChangeListener != null) {
+ // 若光标在起始位置且不是第一个输入框，通知删除当前输入框
if (0 == mSelectionStartBeforeDelete && mIndex != 0) {
mOnTextViewChangeListener.onEditTextDelete(mIndex, getText().toString());
return true;
@@ -153,10 +209,11 @@ 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));
- mOnTextViewChangeListener.onEditTextEnter(mIndex + 1, text);
+ String text = getText().subSequence(selectionStart, length()).toString(); // 光标后文本
+ setText(getText().subSequence(0, selectionStart)); // 保留光标前文本
+ mOnTextViewChangeListener.onEditTextEnter(mIndex + 1, text); // 通知新增输入框
} else {
Log.d(TAG, "OnTextViewChangeListener was not seted");
}
@@ -167,9 +224,16 @@ public class NoteEditText extends EditText {
return super.onKeyUp(keyCode, event);
}
+ /**
+ * 处理焦点变化事件，通知监听器文本是否为空（用于控制操作选项显示）
+ * @param focused 是否获得焦点
+ * @param direction 焦点移动方向
+ * @param previouslyFocusedRect 上一个焦点区域
+ */
@Override
protected void onFocusChanged(boolean focused, int direction, Rect previouslyFocusedRect) {
if (mOnTextViewChangeListener != null) {
+ // 失去焦点且文本为空时，通知无文本；否则通知有文本
if (!focused && TextUtils.isEmpty(getText())) {
mOnTextViewChangeListener.onTextChange(mIndex, false);
} else {
@@ -179,18 +243,24 @@ public class NoteEditText extends EditText {
super.onFocusChanged(focused, direction, previouslyFocusedRect);
}
+ /**
+ * 创建上下文菜单，识别选中的链接并显示对应操作选项（如拨打、打开网页）
+ * @param menu 上下文菜单实例
+ */
@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) {
+ if (urls.length == 1) { // 仅处理单个链接的情况
int defaultResId = 0;
+ // 识别链接协议，匹配对应的菜单资源
for(String schema: sSchemaActionResMap.keySet()) {
if(urls[0].getURL().indexOf(schema) >= 0) {
defaultResId = sSchemaActionResMap.get(schema);
@@ -198,15 +268,16 @@ public class NoteEditText extends EditText {
}
}
+ // 未匹配到已知协议时，使用默认菜单文本
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);
+ urls[0].onClick(NoteEditText.this); // 触发URLSpan的点击事件
return true;
}
});
@@ -214,4 +285,4 @@ public class NoteEditText extends EditText {
}
super.onCreateContextMenu(menu);
}
-}
+}
\ No newline at end of file
diff --git a/src/ui/NoteItemData.java b/src/ui/NoteItemData.java
index 0f5a878..8259487 100644
--- a/src/ui/NoteItemData.java
+++ b/src/ui/NoteItemData.java
@@ -26,57 +26,70 @@ import net.micode.notes.data.Notes.NoteColumns;
import net.micode.notes.tool.DataUtils;
+/**
+ * 小米便签列表项的数据模型类，封装单个便签的核心信息及列表位置属性，用于支撑列表UI展示
+ */
public class NoteItemData {
+ // 数据库查询的列名数组，对应便签表的核心字段
static final String [] PROJECTION = new String [] {
- NoteColumns.ID,
- NoteColumns.ALERTED_DATE,
- NoteColumns.BG_COLOR_ID,
- NoteColumns.CREATED_DATE,
- NoteColumns.HAS_ATTACHMENT,
- NoteColumns.MODIFIED_DATE,
- NoteColumns.NOTES_COUNT,
- NoteColumns.PARENT_ID,
- NoteColumns.SNIPPET,
- NoteColumns.TYPE,
- NoteColumns.WIDGET_ID,
- NoteColumns.WIDGET_TYPE,
+ NoteColumns.ID, // 便签ID
+ NoteColumns.ALERTED_DATE, // 提醒时间
+ NoteColumns.BG_COLOR_ID, // 背景色ID
+ NoteColumns.CREATED_DATE, // 创建时间
+ NoteColumns.HAS_ATTACHMENT, // 是否有附件
+ NoteColumns.MODIFIED_DATE, // 修改时间
+ NoteColumns.NOTES_COUNT, // 文件夹包含的便签数量（仅文件夹类型有效）
+ NoteColumns.PARENT_ID, // 父文件夹ID
+ NoteColumns.SNIPPET, // 内容摘要（文件夹名或便签内容片段）
+ NoteColumns.TYPE, // 类型（便签/文件夹/系统文件夹）
+ NoteColumns.WIDGET_ID, // 桌面插件ID
+ NoteColumns.WIDGET_TYPE, // 桌面插件类型
};
- private static final int ID_COLUMN = 0;
- private static final int ALERTED_DATE_COLUMN = 1;
- private static final int BG_COLOR_ID_COLUMN = 2;
- private static final int CREATED_DATE_COLUMN = 3;
- private static final int HAS_ATTACHMENT_COLUMN = 4;
- private static final int MODIFIED_DATE_COLUMN = 5;
- private static final int NOTES_COUNT_COLUMN = 6;
- private static final int PARENT_ID_COLUMN = 7;
- private static final int SNIPPET_COLUMN = 8;
- private static final int TYPE_COLUMN = 9;
- private static final int WIDGET_ID_COLUMN = 10;
- private static final int WIDGET_TYPE_COLUMN = 11;
-
- private long mId;
- private long mAlertDate;
- private int mBgColorId;
- private long mCreatedDate;
- private boolean mHasAttachment;
- private long mModifiedDate;
- private int mNotesCount;
- private long mParentId;
- private String mSnippet;
- private int mType;
- private int mWidgetId;
- private int mWidgetType;
- private String mName;
- private String mPhoneNumber;
-
- private boolean mIsLastItem;
- private boolean mIsFirstItem;
- private boolean mIsOnlyOneItem;
- private boolean mIsOneNoteFollowingFolder;
- private boolean mIsMultiNotesFollowingFolder;
-
+ // 上述PROJECTION数组中各列的索引常量，用于从Cursor中提取数据
+ private static final int ID_COLUMN = 0; // 便签ID索引
+ private static final int ALERTED_DATE_COLUMN = 1; // 提醒时间索引
+ private static final int BG_COLOR_ID_COLUMN = 2; // 背景色ID索引
+ private static final int CREATED_DATE_COLUMN = 3; // 创建时间索引
+ private static final int HAS_ATTACHMENT_COLUMN = 4; // 是否有附件索引
+ private static final int MODIFIED_DATE_COLUMN = 5; // 修改时间索引
+ private static final int NOTES_COUNT_COLUMN = 6; // 文件夹便签数量索引
+ private static final int PARENT_ID_COLUMN = 7; // 父文件夹ID索引
+ private static final int SNIPPET_COLUMN = 8; // 内容摘要索引
+ private static final int TYPE_COLUMN = 9; // 类型索引
+ private static final int WIDGET_ID_COLUMN = 10; // 桌面插件ID索引
+ private static final int WIDGET_TYPE_COLUMN = 11; // 桌面插件类型索引
+
+ // 便签核心数据字段
+ private long mId; // 便签唯一ID
+ private long mAlertDate; // 提醒时间（毫秒时间戳）
+ private int mBgColorId; // 背景色ID（对应资源文件）
+ private long mCreatedDate; // 创建时间（毫秒时间戳）
+ private boolean mHasAttachment; // 是否有附件（如图片等）
+ private long mModifiedDate; // 最后修改时间（毫秒时间戳）
+ private int mNotesCount; // 文件夹包含的便签数量（仅文件夹类型使用）
+ private long mParentId; // 所属文件夹ID
+ private String mSnippet; // 内容摘要（文件夹名或便签内容的简短展示）
+ private int mType; // 类型（Notes.TYPE_NOTE：便签；TYPE_FOLDER：文件夹等）
+ private int mWidgetId; // 关联的桌面插件ID（无则为无效值）
+ private int mWidgetType; // 桌面插件类型（无则为无效值）
+ private String mName; // 通话记录便签的联系人姓名（非通话记录则为空）
+ private String mPhoneNumber; // 通话记录便签的电话号码（非通话记录则为空）
+
+ // 列表位置属性（用于UI背景样式适配）
+ private boolean mIsLastItem; // 是否为列表最后一项
+ private boolean mIsFirstItem; // 是否为列表第一项
+ private boolean mIsOnlyOneItem; // 是否为列表中唯一一项
+ private boolean mIsOneNoteFollowingFolder; // 是否为文件夹后的唯一便签项
+ private boolean mIsMultiNotesFollowingFolder; // 是否为文件夹后的多个便签项之一
+
+ /**
+ * 构造方法：从数据库查询游标中提取数据初始化便签信息
+ * @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);
@@ -86,19 +99,21 @@ public class NoteItemData {
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) {
+ if (mParentId == Notes.ID_CALL_RECORD_FOLDER) { // 若属于通话记录文件夹
mPhoneNumber = DataUtils.getCallNumberByNoteId(context.getContentResolver(), mId);
if (!TextUtils.isEmpty(mPhoneNumber)) {
- mName = Contact.getContact(context, mPhoneNumber);
+ mName = Contact.getContact(context, mPhoneNumber); // 获取联系人姓名
if (mName == null) {
- mName = mPhoneNumber;
+ mName = mPhoneNumber; // 无联系人时显示电话号码
}
}
}
@@ -106,27 +121,39 @@ public class NoteItemData {
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); // 是否为唯一一项
+
+ // 初始化文件夹后便签的位置属性
mIsMultiNotesFollowingFolder = false;
mIsOneNoteFollowingFolder = false;
+ // 若当前是便签项且不是第一项，检查前一项是否为文件夹
if (mType == Notes.TYPE_NOTE && !mIsFirstItem) {
int position = cursor.getPosition();
- if (cursor.moveToPrevious()) {
+ if (cursor.moveToPrevious()) { // 移动到前一项
+ // 前一项是文件夹或系统文件夹
if (cursor.getInt(TYPE_COLUMN) == Notes.TYPE_FOLDER
|| cursor.getInt(TYPE_COLUMN) == Notes.TYPE_SYSTEM) {
+ // 若游标总数大于当前位置+1，说明文件夹后有多个便签
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");
}
@@ -134,91 +161,159 @@ public class NoteItemData {
}
}
+ /**
+ * 是否为文件夹后的唯一便签项
+ */
public boolean isOneFollowingFolder() {
return mIsOneNoteFollowingFolder;
}
+ /**
+ * 是否为文件夹后的多个便签项之一
+ */
public boolean isMultiFollowingFolder() {
return mIsMultiNotesFollowingFolder;
}
+ /**
+ * 是否为列表最后一项
+ */
public boolean isLast() {
return mIsLastItem;
}
+ /**
+ * 获取通话记录便签的联系人姓名（非通话记录返回空）
+ */
public String getCallName() {
return mName;
}
+ /**
+ * 是否为列表第一项
+ */
public boolean isFirst() {
return mIsFirstItem;
}
+ /**
+ * 是否为列表中唯一一项
+ */
public boolean isSingle() {
return mIsOnlyOneItem;
}
+ /**
+ * 获取便签ID
+ */
public long getId() {
return mId;
}
+ /**
+ * 获取提醒时间（毫秒时间戳）
+ */
public long getAlertDate() {
return mAlertDate;
}
+ /**
+ * 获取创建时间（毫秒时间戳）
+ */
public long getCreatedDate() {
return mCreatedDate;
}
+ /**
+ * 是否有附件
+ */
public boolean hasAttachment() {
return mHasAttachment;
}
+ /**
+ * 获取最后修改时间（毫秒时间戳）
+ */
public long getModifiedDate() {
return mModifiedDate;
}
+ /**
+ * 获取背景色ID
+ */
public int getBgColorId() {
return mBgColorId;
}
+ /**
+ * 获取所属文件夹ID
+ */
public long getParentId() {
return mParentId;
}
+ /**
+ * 获取文件夹包含的便签数量（仅文件夹类型有效）
+ */
public int getNotesCount() {
return mNotesCount;
}
+ /**
+ * 获取所属文件夹ID（与getParentId一致，兼容不同调用场景）
+ */
public long getFolderId () {
return mParentId;
}
+ /**
+ * 获取类型（便签/文件夹/系统文件夹）
+ */
public int getType() {
return mType;
}
+ /**
+ * 获取桌面插件类型
+ */
public int getWidgetType() {
return mWidgetType;
}
+ /**
+ * 获取桌面插件ID
+ */
public int getWidgetId() {
return mWidgetId;
}
+ /**
+ * 获取内容摘要（文件夹名或便签内容片段）
+ */
public String getSnippet() {
return mSnippet;
}
+ /**
+ * 是否设置了提醒（提醒时间>0）
+ */
public boolean hasAlert() {
return (mAlertDate > 0);
}
+ /**
+ * 是否为通话记录便签（属于通话记录文件夹且有电话号码）
+ */
public boolean isCallRecord() {
return (mParentId == Notes.ID_CALL_RECORD_FOLDER && !TextUtils.isEmpty(mPhoneNumber));
}
+ /**
+ * 从游标中获取便签类型
+ * @param cursor 数据库查询结果游标
+ * @return 便签类型（Notes.TYPE_NOTE等）
+ */
public static int getNoteType(Cursor cursor) {
return cursor.getInt(TYPE_COLUMN);
}
-}
+}
\ No newline at end of file
diff --git a/src/ui/NotesListActivity.java b/src/ui/NotesListActivity.java
index e843aec..b80c6ad 100644
--- a/src/ui/NotesListActivity.java
+++ b/src/ui/NotesListActivity.java
@@ -78,71 +78,98 @@ import java.io.InputStream;
import java.io.InputStreamReader;
import java.util.HashSet;
+/**
+ * 笔记列表主界面，负责展示笔记列表、处理用户交互（新建/删除/移动笔记等）
+ */
public class NotesListActivity extends Activity implements OnClickListener, OnItemLongClickListener {
+ // 查询标记：文件夹下的笔记列表查询
private static final int FOLDER_NOTE_LIST_QUERY_TOKEN = 0;
-
+ // 查询标记：文件夹列表查询（用于移动笔记时选择目标文件夹）
private static final int FOLDER_LIST_QUERY_TOKEN = 1;
+ // 上下文菜单选项：删除文件夹
private static final int MENU_FOLDER_DELETE = 0;
-
+ // 上下文菜单选项：查看文件夹
private static final int MENU_FOLDER_VIEW = 1;
-
+ // 上下文菜单选项：重命名文件夹
private static final int MENU_FOLDER_CHANGE_NAME = 2;
+ // SharedPreferences键：记录是否已添加应用介绍笔记
private static final String PREFERENCE_ADD_INTRODUCTION = "net.micode.notes.introduction";
+ /**
+ * 列表状态枚举：
+ * - NOTE_LIST：显示普通笔记列表（根目录）
+ * - SUB_FOLDER：显示子文件夹内容
+ * - CALL_RECORD_FOLDER：显示通话记录文件夹内容
+ */
private enum ListEditState {
NOTE_LIST, SUB_FOLDER, CALL_RECORD_FOLDER
};
+ // 当前列表状态
private ListEditState mState;
-
+ // 异步查询处理器，用于处理ContentProvider的查询操作（避免主线程阻塞）
private BackgroundQueryHandler mBackgroundQueryHandler;
-
+ // 笔记列表适配器，负责将数据绑定到ListView
private NotesListAdapter mNotesListAdapter;
-
+ // 笔记列表视图
private ListView mNotesListView;
-
+ // 新建笔记按钮
private Button mAddNewNote;
-
+ // 触摸事件分发标记：是否将事件分发给ListView
private boolean mDispatch;
-
+ // 触摸起始Y坐标（用于处理新建按钮的透明区域点击）
private int mOriginY;
-
+ // 分发给ListView的Y坐标（修正偏移后的坐标）
private int mDispatchY;
-
+ // 标题栏文本视图
private TextView mTitleBar;
-
+ // 当前所在文件夹ID（默认根目录）
private long mCurrentFolderId;
-
+ // 内容解析器，用于操作ContentProvider
private ContentResolver mContentResolver;
-
+ // 多选模式回调，处理列表多选状态的逻辑
private ModeCallback mModeCallBack;
-
+ // 日志标记
private static final String TAG = "NotesListActivity";
-
+ // 列表滚动速率
public static final int NOTES_LISTVIEW_SCROLL_RATE = 30;
-
+ // 当前聚焦的笔记数据项（用于上下文操作）
private NoteItemData mFocusNoteDataItem;
+ // 普通文件夹查询条件：按父文件夹ID筛选
private static final String NORMAL_SELECTION = NoteColumns.PARENT_ID + "=?";
-
+ // 根目录查询条件：
+ // 1. 非系统类型且父ID为根目录的项
+ // 2. 通话记录文件夹且包含笔记的项
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;
-
@Override
+ /**
+ * Activity创建时调用的生命周期方法，用于初始化界面和数据
+ * @param savedInstanceState 保存的实例状态，用于恢复数据（如屏幕旋转时）
+ */
+ /*Bundle 是一个专门用于存储和传递键值对数据的核心类，设计初衷是为了解决组件间的数据交互问题，尤其适合在生命周期变化时暂存和传递数据*/
protected void onCreate(Bundle savedInstanceState) {
+ // 调用父类Activity的onCreate方法，完成基础初始化
super.onCreate(savedInstanceState);
+ // 设置当前Activity的布局文件为note_list.xml
+ // (布局文件定义了便签列表的UI结构，如ListView、添加按钮等)
setContentView(R.layout.note_list);
+ // 初始化界面资源和成员变量（如列表视图、适配器、事件监听器等）
initResources();
/**
- * Insert an introduction when user firstly use this application
+ * 当用户首次使用应用时，插入一条介绍性便签
+ * （引导用户了解应用功能，仅在首次启动时执行）
*/
setAppInfoFromRawRes();
}
@@ -157,46 +184,83 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
}
}
+ /**
+ * 首次启动应用时，从raw资源读取引导文本并创建引导便签
+ * 仅在用户第一次打开应用时执行，通过SharedPreferences标记避免重复创建
+ */
private void setAppInfoFromRawRes() {
SharedPreferences sp = PreferenceManager.getDefaultSharedPreferences(this);
+
+ // 检查是否已添加过引导便签（通过PREFERENCE_ADD_INTRODUCTION标记判断）
+ // 若为false，说明是首次使用，需要创建引导便签
if (!sp.getBoolean(PREFERENCE_ADD_INTRODUCTION, false)) {
+ // 用于拼接读取到的引导文本内容
+ /*StringBuilder 是 Java 中用于动态拼接字符串的类，属于 java.lang 包*/
StringBuilder sb = new StringBuilder();
+ // 输入流，用于读取raw资源文件，InputStream 是 Java 中处理字节输入流的抽象类，属于 java.io 包
InputStream in = null;
+
try {
- in = getResources().openRawResource(R.raw.introduction);
+ // 打开raw目录下的introduction文件（引导文本内容）
+ in = getResources().openRawResource(R.raw.introduction);
+
+ // 若文件打开成功
if (in != null) {
+ // 构建字符输入流（指定默认编码）
InputStreamReader isr = new InputStreamReader(in);
+ // 缓冲字符流，提高读取效率
BufferedReader br = new BufferedReader(isr);
+ // 缓冲区，每次读取1024个字符
char [] buf = new char[1024];
+ // 记录每次读取的字符长度
int len = 0;
+
+ // 循环读取文件内容，直到末尾（len=-1时结束）
while ((len = br.read(buf)) > 0) {
+ // 将读取到的字符追加到字符串构建器
sb.append(buf, 0, len);
}
} else {
+ // 文件打开失败时记录错误日志并返回
Log.e(TAG, "Read introduction file error");
return;
}
} catch (IOException e) {
+ // 读取过程中发生IO异常时，打印堆栈信息并返回
e.printStackTrace();
return;
} finally {
+ // 确保输入流最终被关闭，释放资源
if(in != null) {
try {
in.close();
} catch (IOException e) {
- // TODO Auto-generated catch block
+ // 关闭流时发生异常，打印堆栈信息
e.printStackTrace();
}
}
}
+ // 创建一个空便签对象
+ // 参数说明：
+ // - 上下文：当前Activity
+ // - 父文件夹ID：根目录（Notes.ID_ROOT_FOLDER）
+ // - 桌面部件ID：无效（因为不是桌面部件生成的便签）
+ // - 部件类型：无效
+ // - 背景色：红色（ResourceParser.RED）
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");
return;
}
@@ -204,42 +268,66 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
}
@Override
+
protected void onStart() {
+ // 调用父类的onStart()方法，确保Activity生命周期的正常执行
super.onStart();
+ // 启动异步查询笔记列表数据的操作
startAsyncNotesListQuery();
}
-
+ /**
+ * 初始化视图资源和监听器
+ */
private void initResources() {
mContentResolver = this.getContentResolver();
mBackgroundQueryHandler = new BackgroundQueryHandler(this.getContentResolver());
- mCurrentFolderId = Notes.ID_ROOT_FOLDER;
+ 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);
- mAddNewNote.setOnTouchListener(new NewNoteOnTouchListener());
+ mAddNewNote.setOnClickListener(this); // 新建笔记按钮点击事件
+ mAddNewNote.setOnTouchListener(new NewNoteOnTouchListener()); // 处理按钮透明区域触摸事件
+
+ // 初始化触摸事件相关变量
mDispatch = false;
mDispatchY = 0;
mOriginY = 0;
+
mTitleBar = (TextView) findViewById(R.id.tv_title_bar);
- mState = ListEditState.NOTE_LIST;
- mModeCallBack = new ModeCallback();
+ mState = ListEditState.NOTE_LIST; // 默认状态为普通笔记列表
+ mModeCallBack = new ModeCallback(); // 初始化多选模式回调
}
+ /**
+ * 多选模式回调类，实现列表项的批量操作（删除、移动等）
+ */
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);
@@ -247,31 +335,36 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
mMoveMenu.setVisible(true);
mMoveMenu.setOnMenuItemClickListener(this);
}
+
mActionMode = mode;
- mNotesListAdapter.setChoiceMode(true);
- mNotesListView.setLongClickable(false);
- mAddNewNote.setVisibility(View.GONE);
+ 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
+ // 更新下拉菜单标题（显示选中数量）
String format = getResources().getString(R.string.menu_select_title, selectedCount);
mDropDownMenu.setTitle(format);
MenuItem item = mDropDownMenu.findItem(R.id.action_select_all);
@@ -286,33 +379,50 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
}
}
+ /**
+ * 准备动作模式时调用（未实现具体逻辑）
+ */
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) {
- mNotesListAdapter.setCheckedItem(position, checked);
- updateMenu();
+ boolean checked) {
+ mNotesListAdapter.setCheckedItem(position, checked); // 更新适配器中选中状态
+ updateMenu(); // 更新菜单显示
}
+ /**
+ * 菜单项点击事件处理（删除/移动）
+ */
public boolean onMenuItemClick(MenuItem item) {
+ // 无选中项时提示
if (mNotesListAdapter.getSelectedCount() == 0) {
Toast.makeText(NotesListActivity.this, getString(R.string.menu_select_none),
Toast.LENGTH_SHORT).show();
@@ -321,23 +431,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();
+ startQueryDestinationFolders(); // 查询目标文件夹列表（用于移动笔记）
break;
default:
return false;
@@ -346,6 +457,9 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
}
}
+ /**
+ * 新建笔记按钮的触摸事件监听器，处理透明区域点击穿透到列表的逻辑
+ */
private class NewNoteOnTouchListener implements OnTouchListener {
public boolean onTouch(View v, MotionEvent event) {
@@ -354,39 +468,39 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
Display display = getWindowManager().getDefaultDisplay();
int screenHeight = display.getHeight();
int newNoteViewHeight = mAddNewNote.getHeight();
- int start = screenHeight - newNoteViewHeight;
- int eventY = start + (int) event.getY();
- /**
- * Minus TitleBar's height
- */
+ int start = screenHeight - newNoteViewHeight; // 按钮在屏幕中的起始Y坐标
+ int eventY = start + (int) event.getY(); // 转换为屏幕坐标
+
+ // 子文件夹状态下，减去标题栏高度修正坐标
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.
+ * 特殊处理：新建按钮的透明区域点击需要穿透到下方列表
+ * 透明区域由公式 y = -0.12x + 94 界定（基于按钮局部坐标）
+ * 若点击位置在透明区域内，则将事件分发给ListView
*/
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);
+ mDispatch = true; // 标记需要分发事件
+ return mNotesListView.dispatchTouchEvent(event); // 分发事件到列表
}
}
break;
}
case MotionEvent.ACTION_MOVE: {
+ // 移动时持续分发事件
if (mDispatch) {
mDispatchY += (int) event.getY() - mOriginY;
event.setLocation(event.getX(), mDispatchY);
@@ -395,6 +509,7 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
break;
}
default: {
+ // 事件结束时分发最后一次事件并重置标记
if (mDispatch) {
event.setLocation(event.getX(), mDispatchY);
mDispatch = false;
@@ -408,27 +523,40 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
};
+ /**
+ * 启动异步查询加载笔记列表数据
+ */
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)
+ String.valueOf(mCurrentFolderId)
}, NoteColumns.TYPE + " DESC," + NoteColumns.MODIFIED_DATE + " DESC");
}
+ /**
+ * 异步查询处理器，继承自AsyncQueryHandler，处理ContentProvider查询
+ */
private final class BackgroundQueryHandler extends AsyncQueryHandler {
public BackgroundQueryHandler(ContentResolver contentResolver) {
super(contentResolver);
}
+ /**
+ * 查询完成时回调
+ */
@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,48 +569,59 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
}
}
+ /**
+ * 显示文件夹列表菜单（用于移动笔记时选择目标文件夹）
+ */
private void showFolderListMenu(Cursor cursor) {
AlertDialog.Builder builder = new AlertDialog.Builder(NotesListActivity.this);
builder.setTitle(R.string.menu_title_select_folder);
final FoldersListAdapter adapter = new FoldersListAdapter(this, cursor);
+ // 设置适配器并处理选择事件
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();
+ mModeCallBack.finishActionMode(); // 结束多选模式
}
});
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);
+ intent.putExtra(Notes.INTENT_EXTRA_FOLDER_ID, mCurrentFolderId); // 传递当前文件夹ID
this.startActivityForResult(intent, REQUEST_CODE_NEW_NODE);
}
+ /**
+ * 批量删除笔记
+ */
private void batchDelete() {
new AsyncTask>() {
protected HashSet doInBackground(Void... unused) {
+ // 获取选中项关联的 widget 信息
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");
@@ -493,36 +632,50 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
@Override
protected void onPostExecute(HashSet widgets) {
+ // 批量删除操作执行完成后回调
if (widgets != null) {
+ // 遍历相关小部件并更新
for (AppWidgetAttribute widget : widgets) {
+ // 校验小部件ID和类型有效性
if (widget.widgetId != AppWidgetManager.INVALID_APPWIDGET_ID
&& widget.widgetType != Notes.TYPE_WIDGET_INVALIDE) {
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);
return;
}
+ // 构建要删除的文件夹ID集合
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,6 +686,10 @@ 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);
@@ -540,15 +697,24 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
this.startActivityForResult(intent, REQUEST_CODE_OPEN_NODE);
}
+ /**
+ * 打开文件夹，显示文件夹内的笔记
+ * @param data 文件夹数据对象
+ */
private void openFolder(NoteItemData data) {
mCurrentFolderId = data.getId();
+ // 异步查询文件夹内的笔记列表
startAsyncNotesListQuery();
+
+ // 根据文件夹类型设置界面状态
if (data.getId() == Notes.ID_CALL_RECORD_FOLDER) {
mState = ListEditState.CALL_RECORD_FOLDER;
- mAddNewNote.setVisibility(View.GONE);
+ mAddNewNote.setVisibility(View.GONE); // 通话记录文件夹隐藏新建笔记按钮
} else {
mState = ListEditState.SUB_FOLDER;
}
+
+ // 设置标题栏文本
if (data.getId() == Notes.ID_CALL_RECORD_FOLDER) {
mTitleBar.setText(R.string.call_record_folder_name);
} else {
@@ -557,9 +723,13 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
mTitleBar.setVisibility(View.VISIBLE);
}
+ /**
+ * 点击事件处理
+ */
public void onClick(View v) {
switch (v.getId()) {
case R.id.btn_new_note:
+ // 点击新建笔记按钮
createNewNote();
break;
default:
@@ -567,6 +737,9 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
}
}
+ /**
+ * 显示软键盘
+ */
private void showSoftInput() {
InputMethodManager inputMethodManager = (InputMethodManager) getSystemService(Context.INPUT_METHOD_SERVICE);
if (inputMethodManager != null) {
@@ -574,17 +747,28 @@ 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());
builder.setTitle(getString(R.string.menu_folder_change_name));
@@ -593,6 +777,7 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
return;
}
} else {
+ // 创建文件夹：清空输入框
etName.setText("");
builder.setTitle(this.getString(R.string.menu_create_folder));
}
@@ -600,7 +785,7 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
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); // 取消时隐藏软键盘
}
});
@@ -608,26 +793,31 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
final Button positive = (Button)dialog.findViewById(android.R.id.button1);
positive.setOnClickListener(new OnClickListener() {
public void onClick(View v) {
- hideSoftInput(etName);
+ 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.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())
});
}
} else if (!TextUtils.isEmpty(name)) {
+ // 创建新文件夹
ContentValues values = new ContentValues();
values.put(NoteColumns.SNIPPET, name);
values.put(NoteColumns.TYPE, Notes.TYPE_FOLDER);
@@ -637,19 +827,19 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
}
});
+ // 初始状态：输入框为空时禁用确定按钮
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 {
@@ -658,29 +848,34 @@ 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();
+ startAsyncNotesListQuery(); // 重新查询数据
mTitleBar.setVisibility(View.GONE);
break;
case CALL_RECORD_FOLDER:
+ // 从通话记录文件夹返回根目录
mCurrentFolderId = Notes.ID_ROOT_FOLDER;
mState = ListEditState.NOTE_LIST;
- mAddNewNote.setVisibility(View.VISIBLE);
+ mAddNewNote.setVisibility(View.VISIBLE); // 显示新建笔记按钮
mTitleBar.setVisibility(View.GONE);
- startAsyncNotesListQuery();
+ startAsyncNotesListQuery(); // 重新查询数据
break;
case NOTE_LIST:
+ // 根目录下直接返回
super.onBackPressed();
break;
default:
@@ -688,8 +883,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) {
@@ -700,32 +901,43 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
}
intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_IDS, new int[] {
- appWidgetId
+ appWidgetId
});
- sendBroadcast(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);
}
super.onContextMenuClosed(menu);
}
+ /**
+ * 上下文菜单项选择事件处理
+ */
@Override
public boolean onContextItemSelected(MenuItem item) {
if (mFocusNoteDataItem == null) {
@@ -734,9 +946,11 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
}
switch (item.getItemId()) {
case MENU_FOLDER_VIEW:
+ // 查看文件夹
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,13 +958,14 @@ 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);
break;
default:
@@ -760,12 +975,16 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
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
+ // 根据同步状态更新同步菜单的文本
menu.findItem(R.id.menu_sync).setTitle(
GTaskSyncService.isSyncing() ? R.string.menu_sync_cancel : R.string.menu_sync);
} else if (mState == ListEditState.SUB_FOLDER) {
@@ -778,38 +997,50 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
return true;
}
+ /**
+ * 选项菜单项选择事件处理
+ */
@Override
public boolean onOptionsItemSelected(MenuItem item) {
switch (item.getItemId()) {
case R.id.menu_new_folder: {
+ // 新建文件夹
showCreateOrModifyFolderDialog(true);
break;
}
case R.id.menu_export_text: {
+ // 导出笔记为文本
exportNoteToText();
break;
}
case R.id.menu_sync: {
+ // 同步相关操作
if (isSyncMode()) {
- if (TextUtils.equals(item.getTitle(), getString(R.string.menu_sync))) {
+ // 已开启同步模式：根据菜单文本判断是开始还是取消同步
+ if (TextUtils.equals(item.getTitle(), getString(R.string.menu_sync))) { // 开始同步
GTaskSyncService.startSync(this);
} else {
+ // 取消同步
GTaskSyncService.cancelSync(this);
}
} else {
+ // 未开启同步模式：跳转到设置页面
startPreferenceActivity();
}
break;
}
case R.id.menu_setting: {
+ // 跳转到设置页面
startPreferenceActivity();
break;
}
case R.id.menu_new_note: {
+ // 新建笔记
createNewNote();
break;
}
case R.id.menu_search:
+ // 触发搜索功能
onSearchRequested();
break;
default:
@@ -818,24 +1049,36 @@ 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);
+ // 异步执行导出操作
new AsyncTask() {
@Override
protected Integer doInBackground(Void... unused) {
+ // 后台执行导出逻辑
return backup.exportToText();
}
@Override
protected void onPostExecute(Integer result) {
+ // 导出完成后根据结果显示对应对话框
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 +1087,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 +1097,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));
@@ -866,32 +1111,51 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
}.execute();
}
+ /**
+ * 判断是否处于同步模式（已设置同步账户）
+ * @return true-同步模式，false-非同步模式
+ */
private boolean isSyncMode() {
return NotesPreferenceActivity.getSyncAccountName(this).trim().length() > 0;
}
+ /**
+ * 启动设置页面
+ */
private void startPreferenceActivity() {
+ // 确定启动上下文（父Activity或当前Activity）
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) {
if (view instanceof NotesListItem) {
+ // 获取点击的列表项数据
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;
}
+ // 根据当前界面状态处理点击
switch (mState) {
case NOTE_LIST:
+ // 根目录下：点击文件夹则打开文件夹，点击笔记则打开笔记
if (item.getType() == Notes.TYPE_FOLDER
|| item.getType() == Notes.TYPE_SYSTEM) {
openFolder(item);
@@ -903,6 +1167,7 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
break;
case SUB_FOLDER:
case CALL_RECORD_FOLDER:
+ // 子文件夹或通话记录文件夹下：点击笔记则打开笔记
if (item.getType() == Notes.TYPE_NOTE) {
openNode(item);
} else {
@@ -917,11 +1182,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,
Notes.CONTENT_NOTE_URI,
@@ -935,20 +1206,27 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
NoteColumns.MODIFIED_DATE + " DESC");
}
+ /**
+ * 列表项长按事件处理
+ */
public boolean onItemLongClick(AdapterView parent, View view, int position, long id) {
if (view instanceof NotesListItem) {
+ // 获取长按的列表项数据
mFocusNoteDataItem = ((NotesListItem) view).getItemData();
+ // 如果是笔记且未处于选择模式，启动动作模式（批量操作）
if (mFocusNoteDataItem.getType() == Notes.TYPE_NOTE && !mNotesListAdapter.isInChoiceMode()) {
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;
- }
-}
+ }}
\ No newline at end of file
diff --git a/src/ui/NotesListAdapter.java b/src/ui/NotesListAdapter.java
index 51c9cb9..6ab7b8e 100644
--- a/src/ui/NotesListAdapter.java
+++ b/src/ui/NotesListAdapter.java
@@ -31,18 +31,30 @@ import java.util.HashSet;
import java.util.Iterator;
+/**
+ * 便签列表适配器，用于将便签数据与列表视图绑定，支持多选操作
+ * 继承自CursorAdapter，通过Cursor获取数据库中的便签数据
+ */
public class NotesListAdapter extends CursorAdapter {
private static final String TAG = "NotesListAdapter";
- private Context mContext;
- private HashMap mSelectedIndex;
- private int mNotesCount;
- private boolean mChoiceMode;
+ private Context mContext; // 上下文对象
+ private HashMap mSelectedIndex; // 存储选中项的位置和状态
+ private int mNotesCount; // 便签总数（不包含文件夹）
+ private boolean mChoiceMode; // 是否处于选择模式
+ /**
+ * 桌面插件属性封装类
+ * 用于存储选中项中包含的桌面插件信息
+ */
public static class AppWidgetAttribute {
- public int widgetId;
- public int widgetType;
+ public int widgetId; // 插件ID
+ public int widgetType; // 插件类型
};
+ /**
+ * 构造方法
+ * @param context 上下文对象
+ */
public NotesListAdapter(Context context) {
super(context, null);
mSelectedIndex = new HashMap();
@@ -50,38 +62,71 @@ public class NotesListAdapter extends CursorAdapter {
mNotesCount = 0;
}
+ /**
+ * 创建新的列表项视图
+ * @param context 上下文
+ * @param cursor 数据游标
+ * @param parent 父容器
+ * @return 新创建的NotesListItem视图
+ */
@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 是否选中
+ */
public void setCheckedItem(final int position, final boolean checked) {
mSelectedIndex.put(position, checked);
- notifyDataSetChanged();
+ notifyDataSetChanged(); // 通知列表刷新
}
+ /**
+ * 判断是否处于选择模式
+ * @return 是否为选择模式
+ */
public boolean isInChoiceMode() {
return mChoiceMode;
}
+ /**
+ * 设置选择模式
+ * @param mode 选择模式开关
+ */
public void setChoiceMode(boolean mode) {
- mSelectedIndex.clear();
+ mSelectedIndex.clear(); // 清除选中状态
mChoiceMode = mode;
}
+ /**
+ * 全选或取消全选所有便签（仅对普通便签有效）
+ * @param checked 是否选中
+ */
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,11 +134,16 @@ public class NotesListAdapter extends CursorAdapter {
}
}
+ /**
+ * 获取所有选中项的ID集合
+ * @return 选中项ID的HashSet
+ */
public HashSet getSelectedItemIds() {
HashSet itemSet = new HashSet();
for (Integer position : mSelectedIndex.keySet()) {
if (mSelectedIndex.get(position) == true) {
Long id = getItemId(position);
+ // 过滤根文件夹ID（不应被选中）
if (id == Notes.ID_ROOT_FOLDER) {
Log.d(TAG, "Wrong item id, should not happen");
} else {
@@ -101,10 +151,13 @@ public class NotesListAdapter extends CursorAdapter {
}
}
}
-
return itemSet;
}
+ /**
+ * 获取所有选中项中的桌面插件属性
+ * @return 插件属性的HashSet
+ */
public HashSet getSelectedWidget() {
HashSet itemSet = new HashSet();
for (Integer position : mSelectedIndex.keySet()) {
@@ -116,9 +169,7 @@ public class NotesListAdapter extends CursorAdapter {
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");
return null;
@@ -128,6 +179,10 @@ public class NotesListAdapter extends CursorAdapter {
return itemSet;
}
+ /**
+ * 获取选中项的数量
+ * @return 选中项数量
+ */
public int getSelectedCount() {
Collection values = mSelectedIndex.values();
if (null == values) {
@@ -143,11 +198,20 @@ public class NotesListAdapter extends CursorAdapter {
return count;
}
+ /**
+ * 判断是否所有便签都被选中
+ * @return 是否全选
+ */
public boolean isAllSelected() {
int checkedCount = getSelectedCount();
return (checkedCount != 0 && checkedCount == mNotesCount);
}
+ /**
+ * 判断指定位置的项是否被选中
+ * @param position 列表项位置
+ * @return 是否选中
+ */
public boolean isSelectedItem(final int position) {
if (null == mSelectedIndex.get(position)) {
return false;
@@ -155,23 +219,34 @@ public class NotesListAdapter extends CursorAdapter {
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;
for (int i = 0; i < getCount(); i++) {
Cursor c = (Cursor) getItem(i);
if (c != null) {
+ // 仅统计类型为普通便签的项
if (NoteItemData.getNoteType(c) == Notes.TYPE_NOTE) {
mNotesCount++;
}
@@ -181,4 +256,4 @@ public class NotesListAdapter extends CursorAdapter {
}
}
}
-}
+}
\ No newline at end of file
diff --git a/src/ui/NotesListItem.java b/src/ui/NotesListItem.java
index 1221e80..e3fd735 100644
--- a/src/ui/NotesListItem.java
+++ b/src/ui/NotesListItem.java
@@ -30,17 +30,27 @@ import net.micode.notes.tool.DataUtils;
import net.micode.notes.tool.ResourceParser.NoteItemBgResources;
+/**
+ * 小米便签列表中的单个项视图
+ * 负责展示便签、文件夹或通话记录的内容及状态，支持多选模式
+ */
public class NotesListItem extends LinearLayout {
- private ImageView mAlert;
- private TextView mTitle;
- private TextView mTime;
- private TextView mCallName;
- private NoteItemData mItemData;
- private CheckBox mCheckBox;
+ private ImageView mAlert; // 提醒图标（显示闹钟或通话记录图标）
+ private TextView mTitle; // 标题/内容文本（显示便签内容、文件夹名称等）
+ private TextView mTime; // 时间文本（显示最后修改时间）
+ private TextView mCallName; // 通话记录联系人名称（仅通话记录便签显示）
+ private NoteItemData mItemData; // 当前项对应的数据模型
+ private CheckBox mCheckBox; // 多选模式下的复选框
+ /**
+ * 构造方法：初始化布局和控件
+ * @param context 上下文对象
+ */
public NotesListItem(Context context) {
super(context);
+ // 加载列表项布局文件
inflate(context, R.layout.note_item, this);
+ // 绑定UI控件
mAlert = (ImageView) findViewById(R.id.iv_alert_icon);
mTitle = (TextView) findViewById(R.id.tv_title);
mTime = (TextView) findViewById(R.id.tv_time);
@@ -48,7 +58,15 @@ public class NotesListItem extends LinearLayout {
mCheckBox = (CheckBox) findViewById(android.R.id.checkbox);
}
+ /**
+ * 绑定数据到当前列表项，根据数据类型和模式展示不同样式
+ * @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);
@@ -57,33 +75,44 @@ public class NotesListItem extends LinearLayout {
}
mItemData = data;
+
+ // 处理通话记录文件夹（特殊系统文件夹）
if (data.getId() == Notes.ID_CALL_RECORD_FOLDER) {
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.setText(data.getCallName()); // 显示联系人名称
+ mTitle.setTextAppearance(context, R.style.TextAppearanceSecondaryItem);
+ mTitle.setText(DataUtils.getFormattedSnippet(data.getSnippet())); // 显示便签内容片段
+ // 显示提醒图标（如有）
if (data.hasAlert()) {
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);
+ // 普通文件夹：显示名称和包含的便签数量
if (data.getType() == Notes.TYPE_FOLDER) {
mTitle.setText(data.getSnippet()
+ context.getString(R.string.format_folder_files_count,
- data.getNotesCount()));
+ data.getNotesCount()));
mAlert.setVisibility(View.GONE);
+
+ // 普通便签：显示内容片段和提醒状态
} else {
mTitle.setText(DataUtils.getFormattedSnippet(data.getSnippet()));
if (data.hasAlert()) {
@@ -94,29 +123,47 @@ public class NotesListItem extends LinearLayout {
}
}
}
+
+ // 显示最后修改时间（相对时间格式，如"1小时前"）
mTime.setText(DateUtils.getRelativeTimeSpanString(data.getModifiedDate()));
+ // 设置项背景样式
setBackground(data);
}
+ /**
+ * 根据便签类型和位置设置背景样式
+ * @param data 便签数据模型
+ */
private void setBackground(NoteItemData data) {
- int id = data.getBgColorId();
+ int bgColorId = data.getBgColorId(); // 获取背景色ID
+
+ // 普通便签：根据位置（首项/末项/单项等）设置不同背景
if (data.getType() == Notes.TYPE_NOTE) {
if (data.isSingle() || data.isOneFollowingFolder()) {
- setBackgroundResource(NoteItemBgResources.getNoteBgSingleRes(id));
+ // 单项或文件夹后的唯一便签
+ setBackgroundResource(NoteItemBgResources.getNoteBgSingleRes(bgColorId));
} else if (data.isLast()) {
- setBackgroundResource(NoteItemBgResources.getNoteBgLastRes(id));
+ // 列表中的最后一项
+ setBackgroundResource(NoteItemBgResources.getNoteBgLastRes(bgColorId));
} else if (data.isFirst() || data.isMultiFollowingFolder()) {
- setBackgroundResource(NoteItemBgResources.getNoteBgFirstRes(id));
+ // 首项或文件夹后的多个便签中的第一项
+ setBackgroundResource(NoteItemBgResources.getNoteBgFirstRes(bgColorId));
} else {
- setBackgroundResource(NoteItemBgResources.getNoteBgNormalRes(id));
+ // 中间项
+ setBackgroundResource(NoteItemBgResources.getNoteBgNormalRes(bgColorId));
}
} else {
+ // 文件夹：使用固定的文件夹背景
setBackgroundResource(NoteItemBgResources.getFolderBgRes());
}
}
+ /**
+ * 获取当前项的数据模型
+ * @return 便签数据模型
+ */
public NoteItemData getItemData() {
return mItemData;
}
-}
+}
\ No newline at end of file
diff --git a/src/ui/NotesPreferenceActivity.java b/src/ui/NotesPreferenceActivity.java
index 07c5f7e..a5761bb 100644
--- a/src/ui/NotesPreferenceActivity.java
+++ b/src/ui/NotesPreferenceActivity.java
@@ -48,41 +48,52 @@ import net.micode.notes.data.Notes.NoteColumns;
import net.micode.notes.gtask.remote.GTaskSyncService;
+/**
+ * 小米便签的设置页面
+ * 负责账号管理、同步控制及偏好设置，支持便签数据同步功能
+ */
public class NotesPreferenceActivity extends PreferenceActivity {
+ // 偏好设置存储名称
public static final String PREFERENCE_NAME = "notes_preferences";
-
+ // 同步账号名称的偏好键
public static final String PREFERENCE_SYNC_ACCOUNT_NAME = "pref_key_account_name";
-
+ // 最后同步时间的偏好键
public static final String PREFERENCE_LAST_SYNC_TIME = "pref_last_sync_time";
-
+ // 背景颜色设置的偏好键
public static final String PREFERENCE_SET_BG_COLOR_KEY = "pref_key_bg_random_appear";
+ // 同步账号设置分类的键
private static final String PREFERENCE_SYNC_ACCOUNT_KEY = "pref_sync_account_key";
-
+ // 账号权限过滤键
private static final String AUTHORITIES_FILTER_KEY = "authorities";
+ // 账号设置分类
private PreferenceCategory mAccountCategory;
-
+ // 同步服务广播接收器
private GTaskReceiver mReceiver;
-
+ // 原始账号列表（用于检测新添加的账号）
private Account[] mOriAccounts;
-
+ // 是否添加了新账号的标记
private boolean mHasAddedAccount;
@Override
protected void onCreate(Bundle icicle) {
super.onCreate(icicle);
- /* using the app icon for navigation */
+ // 设置ActionBar支持返回导航
getActionBar().setDisplayHomeAsUpEnabled(true);
+ // 加载偏好设置布局
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);
@@ -92,8 +103,7 @@ public class NotesPreferenceActivity extends PreferenceActivity {
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) {
@@ -113,17 +123,22 @@ public class NotesPreferenceActivity extends PreferenceActivity {
}
}
+ // 刷新UI显示
refreshUI();
}
@Override
protected void onDestroy() {
+ // 注销广播接收器
if (mReceiver != null) {
unregisterReceiver(mReceiver);
}
super.onDestroy();
}
+ /**
+ * 加载账号设置项到偏好页面
+ */
private void loadAccountPreference() {
mAccountCategory.removeAll();
@@ -131,20 +146,21 @@ public class NotesPreferenceActivity extends PreferenceActivity {
final String defaultAccount = getSyncAccountName(this);
accountPref.setTitle(getString(R.string.preferences_account_title));
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,15 +170,19 @@ 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() {
public void onClick(View v) {
+ // 取消同步
GTaskSyncService.cancelSync(NotesPreferenceActivity.this);
}
});
@@ -170,13 +190,15 @@ public class NotesPreferenceActivity extends PreferenceActivity {
syncButton.setText(getString(R.string.preferences_button_sync_immediately));
syncButton.setOnClickListener(new View.OnClickListener() {
public void onClick(View v) {
+ // 立即同步
GTaskSyncService.startSync(NotesPreferenceActivity.this);
}
});
}
+ // 未设置账号时禁用同步按钮
syncButton.setEnabled(!TextUtils.isEmpty(getSyncAccountName(this)));
- // set last sync time
+ // 设置最后同步时间显示
if (GTaskSyncService.isSyncing()) {
lastSyncTimeView.setText(GTaskSyncService.getProgressString());
lastSyncTimeView.setVisibility(View.VISIBLE);
@@ -193,23 +215,30 @@ public class NotesPreferenceActivity extends PreferenceActivity {
}
}
+ /**
+ * 刷新整个UI界面
+ */
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));
TextView subtitleTextView = (TextView) titleView.findViewById(R.id.account_dialog_subtitle);
subtitleTextView.setText(getString(R.string.preferences_dialog_select_account_tips));
-
dialogBuilder.setCustomTitle(titleView);
dialogBuilder.setPositiveButton(null, null);
+ // 获取谷歌账号列表
Account[] accounts = getGoogleAccounts();
String defAccount = getSyncAccountName(this);
@@ -221,12 +250,14 @@ public class NotesPreferenceActivity extends PreferenceActivity {
final CharSequence[] itemMapping = items;
int checkedItem = -1;
int index = 0;
+ // 构建账号选择列表
for (Account account : accounts) {
if (TextUtils.equals(account.name, defAccount)) {
checkedItem = index;
}
items[index++] = account.name;
}
+ // 设置单选列表点击事件
dialogBuilder.setSingleChoiceItems(items, checkedItem,
new DialogInterface.OnClickListener() {
public void onClick(DialogInterface dialog, int which) {
@@ -237,6 +268,7 @@ public class NotesPreferenceActivity extends PreferenceActivity {
});
}
+ // 添加"添加账号"选项
View addAccountView = LayoutInflater.from(this).inflate(R.layout.add_account_text, null);
dialogBuilder.setView(addAccountView);
@@ -244,9 +276,10 @@ public class NotesPreferenceActivity extends PreferenceActivity {
addAccountView.setOnClickListener(new View.OnClickListener() {
public void onClick(View v) {
mHasAddedAccount = true;
+ // 跳转到添加账号设置页面
Intent intent = new Intent("android.settings.ADD_ACCOUNT_SETTINGS");
intent.putExtra(AUTHORITIES_FILTER_KEY, new String[] {
- "gmail-ls"
+ "gmail-ls"
});
startActivityForResult(intent, -1);
dialog.dismiss();
@@ -254,9 +287,13 @@ 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,
@@ -265,6 +302,7 @@ public class NotesPreferenceActivity extends PreferenceActivity {
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,8 +311,10 @@ 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();
}
@@ -283,11 +323,19 @@ public class NotesPreferenceActivity extends PreferenceActivity {
dialogBuilder.show();
}
+ /**
+ * 获取设备上的谷歌账号列表
+ * @return 谷歌账号数组
+ */
private Account[] getGoogleAccounts() {
AccountManager accountManager = AccountManager.get(this);
return accountManager.getAccountsByType("com.google");
}
+ /**
+ * 设置同步账号并更新本地数据
+ * @param account 账号名称
+ */
private void setSyncAccount(String account) {
if (!getSyncAccountName(this).equals(account)) {
SharedPreferences settings = getSharedPreferences(PREFERENCE_NAME, Context.MODE_PRIVATE);
@@ -299,10 +347,10 @@ public class NotesPreferenceActivity extends PreferenceActivity {
}
editor.commit();
- // clean up last sync time
+ // 清除最后同步时间
setLastSyncTime(this, 0);
- // clean up local gtask related info
+ // 清除本地GTASK相关信息（异步执行）
new Thread(new Runnable() {
public void run() {
ContentValues values = new ContentValues();
@@ -318,6 +366,9 @@ public class NotesPreferenceActivity extends PreferenceActivity {
}
}
+ /**
+ * 移除当前同步账号并清理数据
+ */
private void removeSyncAccount() {
SharedPreferences settings = getSharedPreferences(PREFERENCE_NAME, Context.MODE_PRIVATE);
SharedPreferences.Editor editor = settings.edit();
@@ -329,7 +380,7 @@ public class NotesPreferenceActivity extends PreferenceActivity {
}
editor.commit();
- // clean up local gtask related info
+ // 清除本地GTASK相关信息（异步执行）
new Thread(new Runnable() {
public void run() {
ContentValues values = new ContentValues();
@@ -340,12 +391,22 @@ public class NotesPreferenceActivity extends PreferenceActivity {
}).start();
}
+ /**
+ * 获取保存的同步账号名称
+ * @param context 上下文
+ * @return 账号名称，为空表示未设置
+ */
public static String getSyncAccountName(Context context) {
SharedPreferences settings = context.getSharedPreferences(PREFERENCE_NAME,
Context.MODE_PRIVATE);
return settings.getString(PREFERENCE_SYNC_ACCOUNT_NAME, "");
}
+ /**
+ * 保存最后同步时间
+ * @param context 上下文
+ * @param time 时间戳
+ */
public static void setLastSyncTime(Context context, long time) {
SharedPreferences settings = context.getSharedPreferences(PREFERENCE_NAME,
Context.MODE_PRIVATE);
@@ -354,16 +415,26 @@ public class NotesPreferenceActivity extends PreferenceActivity {
editor.commit();
}
+ /**
+ * 获取最后同步时间
+ * @param context 上下文
+ * @return 时间戳，0表示从未同步过
+ */
public static long getLastSyncTime(Context context) {
SharedPreferences settings = context.getSharedPreferences(PREFERENCE_NAME,
Context.MODE_PRIVATE);
return settings.getLong(PREFERENCE_LAST_SYNC_TIME, 0);
}
+ /**
+ * 监听同步服务广播的接收器
+ * 用于同步过程中更新UI状态
+ */
private class GTaskReceiver extends BroadcastReceiver {
@Override
public void onReceive(Context context, Intent intent) {
+ // 刷新UI显示同步状态
refreshUI();
if (intent.getBooleanExtra(GTaskSyncService.GTASK_SERVICE_BROADCAST_IS_SYNCING, false)) {
TextView syncStatus = (TextView) findViewById(R.id.prefenerece_sync_status_textview);
@@ -374,9 +445,13 @@ public class NotesPreferenceActivity extends PreferenceActivity {
}
}
+ /**
+ * 处理菜单选项点击事件
+ */
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 +460,4 @@ public class NotesPreferenceActivity extends PreferenceActivity {
return false;
}
}
-}
+}
\ No newline at end of file
diff --git a/src/widget/NoteWidgetProvider.java b/src/widget/NoteWidgetProvider.java
index ec6f819..e953109 100644
--- a/src/widget/NoteWidgetProvider.java
+++ b/src/widget/NoteWidgetProvider.java
@@ -32,24 +32,36 @@ 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;
private static final String TAG = "NoteWidgetProvider";
+ /**
+ * 当小部件被删除时调用
+ * 清除数据库中与该小部件关联的记录
+ */
@Override
public void onDeleted(Context context, int[] appWidgetIds) {
ContentValues values = new ContentValues();
+ // 将小部件ID设为无效值
values.put(NoteColumns.WIDGET_ID, AppWidgetManager.INVALID_APPWIDGET_ID);
for (int i = 0; i < appWidgetIds.length; i++) {
+ // 更新数据库中关联该小部件的便签记录
context.getContentResolver().update(Notes.CONTENT_NOTE_URI,
values,
NoteColumns.WIDGET_ID + "=?",
@@ -57,76 +69,119 @@ public abstract class NoteWidgetProvider extends AppWidgetProvider {
}
}
+ /**
+ * 获取与指定小部件关联的便签信息
+ * @param context 上下文
+ * @param widgetId 小部件ID
+ * @return 包含便签信息的游标
+ */
private Cursor getNoteWidgetInfo(Context context, int widgetId) {
return context.getContentResolver().query(Notes.CONTENT_NOTE_URI,
PROJECTION,
+ // 查询条件：小部件ID匹配且不在回收站中
NoteColumns.WIDGET_ID + "=? AND " + NoteColumns.PARENT_ID + "<>?",
new String[] { String.valueOf(widgetId), String.valueOf(Notes.ID_TRASH_FOLER) },
null);
}
+ /**
+ * 公开的更新方法，调用带隐私模式参数的私有更新方法
+ */
protected void update(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds) {
update(context, appWidgetManager, appWidgetIds, false);
}
+ /**
+ * 核心更新方法，更新小部件的UI显示
+ * @param context 上下文
+ * @param appWidgetManager 小部件管理器
+ * @param appWidgetIds 需要更新的小部件ID数组
+ * @param privacyMode 是否隐私模式（隐藏内容）
+ */
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) {
+ // 默认背景颜色ID
int bgId = ResourceParser.getDefaultBgId(context);
+ // 便签内容摘要
String snippet = "";
+ // 点击小部件时的跳转意图
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());
+ // 查询与当前小部件关联的便签数据
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;
}
+ // 从游标中获取数据
snippet = c.getString(COLUMN_SNIPPET);
bgId = c.getInt(COLUMN_BG_COLOR_ID);
intent.putExtra(Intent.EXTRA_UID, c.getLong(COLUMN_ID));
- intent.setAction(Intent.ACTION_VIEW);
+ intent.setAction(Intent.ACTION_VIEW); // 查看已有便签
} else {
+ // 无关联便签时显示默认文本
snippet = context.getResources().getString(R.string.widget_havenot_content);
- intent.setAction(Intent.ACTION_INSERT_OR_EDIT);
+ intent.setAction(Intent.ACTION_INSERT_OR_EDIT); // 新建便签
}
+ // 关闭游标释放资源
if (c != null) {
c.close();
}
+ // 加载小部件布局
RemoteViews rv = new RemoteViews(context.getPackageName(), getLayoutId());
+ // 设置背景图片
rv.setImageViewResource(R.id.widget_bg_image, getBgResourceId(bgId));
intent.putExtra(Notes.INTENT_EXTRA_BACKGROUND_ID, bgId);
- /**
- * Generate the pending intent to start host for the widget
- */
+
+ // 创建点击事件的PendingIntent
PendingIntent 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
+ * 由子类实现不同尺寸小部件的背景资源
+ */
protected abstract int getBgResourceId(int bgId);
+ /**
+ * 抽象方法：获取布局ID
+ * 由子类实现不同尺寸小部件的布局文件
+ */
protected abstract int getLayoutId();
+ /**
+ * 抽象方法：获取小部件类型
+ * 由子类定义具体的小部件类型（如2x、4x等）
+ */
protected abstract int getWidgetType();
-}
+}
\ No newline at end of file
diff --git a/src/widget/NoteWidgetProvider_2x.java b/src/widget/NoteWidgetProvider_2x.java
index adcb2f7..f48b84b 100644
--- a/src/widget/NoteWidgetProvider_2x.java
+++ b/src/widget/NoteWidgetProvider_2x.java
@@ -23,25 +23,54 @@ import net.micode.notes.R;
import net.micode.notes.data.Notes;
import net.micode.notes.tool.ResourceParser;
-
+/**
+ * 2x尺寸的便签桌面小部件实现类
+ * 继承自NoteWidgetProvider，专注于2x尺寸的布局、背景和类型定义
+ */
public class NoteWidgetProvider_2x extends NoteWidgetProvider {
+
+ /**
+ * 小部件更新回调方法
+ * 当小部件需要更新时（如添加到桌面、系统触发更新）调用
+ * @param context 上下文对象，提供应用环境信息
+ * @param appWidgetManager 小部件管理器，用于更新小部件状态
+ * @param appWidgetIds 需要更新的小部件ID数组
+ */
@Override
public void onUpdate(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds) {
+ // 调用父类的update方法执行通用更新逻辑（如查询数据、绑定事件）
super.update(context, appWidgetManager, appWidgetIds);
}
+ /**
+ * 实现抽象方法，返回2x尺寸小部件的布局文件ID
+ * 布局文件定义了小部件的UI结构（如文本位置、背景容器等）
+ * @return 2x小部件布局ID（R.layout.widget_2x）
+ */
@Override
protected int getLayoutId() {
return R.layout.widget_2x;
}
+ /**
+ * 实现抽象方法，返回2x尺寸小部件的背景资源ID
+ * 根据便签的背景色ID（bgId）获取对应的2x尺寸背景图
+ * @param bgId 便签背景色ID（如红色、黄色等）
+ * @return 2x小部件对应的背景资源ID
+ */
@Override
protected int getBgResourceId(int bgId) {
+ // 通过资源解析工具获取2x尺寸的背景资源
return ResourceParser.WidgetBgResources.getWidget2xBgResource(bgId);
}
+ /**
+ * 实现抽象方法，返回2x尺寸小部件的类型标识
+ * 用于系统区分不同尺寸的小部件，关联对应的数据和逻辑
+ * @return 2x小部件类型标识（Notes.TYPE_WIDGET_2X）
+ */
@Override
protected int getWidgetType() {
return Notes.TYPE_WIDGET_2X;
}
-}
+}
\ No newline at end of file
diff --git a/src/widget/NoteWidgetProvider_4x.java b/src/widget/NoteWidgetProvider_4x.java
index c12a02e..59bf459 100644
--- a/src/widget/NoteWidgetProvider_4x.java
+++ b/src/widget/NoteWidgetProvider_4x.java
@@ -24,23 +24,49 @@ import net.micode.notes.data.Notes;
import net.micode.notes.tool.ResourceParser;
+/**
+ * 小米便签4x尺寸桌面小部件的实现类，继承自NoteWidgetProvider，负责4x小部件的布局、背景和类型管理
+ */
public class NoteWidgetProvider_4x extends NoteWidgetProvider {
+ /**
+ * 当系统触发小部件更新时调用（如小部件添加到桌面、定时刷新）
+ * 调用父类的update方法，触发通用更新逻辑（查询便签数据、渲染视图等）
+ * @param context 应用上下文，用于访问资源和数据库
+ * @param appWidgetManager 系统小部件管理器，负责更新小部件视图
+ * @param appWidgetIds 需要更新的小部件ID数组
+ */
@Override
public void onUpdate(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds) {
super.update(context, appWidgetManager, appWidgetIds);
}
+ /**
+ * 提供4x尺寸小部件的布局文件ID
+ * 布局文件widget_4x.xml定义了该小部件的UI结构（如文本区域、背景容器等）
+ * @return 4x小部件的布局资源ID
+ */
protected int getLayoutId() {
return R.layout.widget_4x;
}
+ /**
+ * 根据背景ID（bgId）获取4x小部件对应的背景资源
+ * 通过ResourceParser工具类解析，确保背景与便签设置的颜色一致
+ * @param bgId 背景标识ID（如红色、蓝色等）
+ * @return 4x小部件的背景资源ID
+ */
@Override
protected int getBgResourceId(int bgId) {
return ResourceParser.WidgetBgResources.getWidget4xBgResource(bgId);
}
+ /**
+ * 返回4x小部件的类型标识，用于父类逻辑中区分小部件尺寸
+ * 与Notes类中定义的TYPE_WIDGET_4X常量对应，确保数据关联正确
+ * @return 4x小部件的类型标识
+ */
@Override
protected int getWidgetType() {
return Notes.TYPE_WIDGET_4X;
}
-}
+}
\ No newline at end of file