java

src/net/micode/notes/model/WorkingNote.java

@@ -32,105 +32,113 @@ import net.micode.notes.data.Notes.TextNote;
 import net.micode.notes.tool.ResourceParser.NoteBgResources;
 
 
+// 工作笔记类，用于管理笔记的创建、加载、保存等操作
 public class WorkingNote {
-    // Note for the working note
+    // 当前笔记对象
     private Note mNote;
-    // Note Id
+    // 笔记ID
     private long mNoteId;
-    // Note content
+    // 笔记内容
     private String mContent;
-    // Note mode
+    // 笔记模式（如普通模式、清单模式等）
     private int mMode;
 
+    // 提醒日期
     private long mAlertDate;
 
+    // 修改日期
     private long mModifiedDate;
 
+    // 背景颜色资源ID
     private int mBgColorId;
 
+    // 关联的小部件ID
     private int mWidgetId;
 
+    // 小部件类型
     private int mWidgetType;
 
+    // 所属文件夹ID
     private long mFolderId;
 
+    // 上下文对象
     private Context mContext;
 
+    // 日志标签
     private static final String TAG = "WorkingNote";
 
+    // 是否已删除
     private boolean mIsDeleted;
 
+    // 笔记设置变更监听器
     private NoteSettingChangedListener mNoteSettingStatusListener;
 
+    // 数据查询投影列（数据库查询字段）
     public static final String[] DATA_PROJECTION = new String[] {
-            DataColumns.ID,
-            DataColumns.CONTENT,
-            DataColumns.MIME_TYPE,
-            DataColumns.DATA1,
-            DataColumns.DATA2,
-            DataColumns.DATA3,
-            DataColumns.DATA4,
+            DataColumns.ID,          // 数据ID
+            DataColumns.CONTENT,     // 内容
+            DataColumns.MIME_TYPE,   // MIME类型
+            DataColumns.DATA1,       // 数据1
+            DataColumns.DATA2,       // 数据2
+            DataColumns.DATA3,       // 数据3
+            DataColumns.DATA4,       // 数据4
     };
 
+    // 笔记查询投影列
     public static final String[] NOTE_PROJECTION = new String[] {
-            NoteColumns.PARENT_ID,
-            NoteColumns.ALERTED_DATE,
-            NoteColumns.BG_COLOR_ID,
-            NoteColumns.WIDGET_ID,
-            NoteColumns.WIDGET_TYPE,
-            NoteColumns.MODIFIED_DATE
+            NoteColumns.PARENT_ID,        // 父文件夹ID
+            NoteColumns.ALERTED_DATE,     // 提醒日期
+            NoteColumns.BG_COLOR_ID,      // 背景颜色ID
+            NoteColumns.WIDGET_ID,        // 小部件ID
+            NoteColumns.WIDGET_TYPE,      // 小部件类型
+            NoteColumns.MODIFIED_DATE     // 修改日期
     };
 
-    private static final int DATA_ID_COLUMN = 0;
-
-    private static final int DATA_CONTENT_COLUMN = 1;
-
-    private static final int DATA_MIME_TYPE_COLUMN = 2;
-
-    private static final int DATA_MODE_COLUMN = 3;
-
-    private static final int NOTE_PARENT_ID_COLUMN = 0;
-
-    private static final int NOTE_ALERTED_DATE_COLUMN = 1;
-
-    private static final int NOTE_BG_COLOR_ID_COLUMN = 2;
-
-    private static final int NOTE_WIDGET_ID_COLUMN = 3;
-
-    private static final int NOTE_WIDGET_TYPE_COLUMN = 4;
-
-    private static final int NOTE_MODIFIED_DATE_COLUMN = 5;
-
-    // New note construct
+    // 列索引常量
+    private static final int DATA_ID_COLUMN = 0;                // 数据ID列索引
+    private static final int DATA_CONTENT_COLUMN = 1;           // 内容列索引
+    private static final int DATA_MIME_TYPE_COLUMN = 2;         // MIME类型列索引
+    private static final int DATA_MODE_COLUMN = 3;              // 模式列索引
+    private static final int NOTE_PARENT_ID_COLUMN = 0;         // 父文件夹ID列索引
+    private static final int NOTE_ALERTED_DATE_COLUMN = 1;      // 提醒日期列索引
+    private static final int NOTE_BG_COLOR_ID_COLUMN = 2;       // 背景颜色ID列索引
+    private static final int NOTE_WIDGET_ID_COLUMN = 3;         // 小部件ID列索引
+    private static final int NOTE_WIDGET_TYPE_COLUMN = 4;       // 小部件类型列索引
+    private static final int NOTE_MODIFIED_DATE_COLUMN = 5;     // 修改日期列索引
+
+    // 构造函数：创建新笔记
     private WorkingNote(Context context, long folderId) {
         mContext = context;
         mAlertDate = 0;
-        mModifiedDate = System.currentTimeMillis();
+        mModifiedDate = System.currentTimeMillis();  // 设置当前时间为修改时间
         mFolderId = folderId;
         mNote = new Note();
         mNoteId = 0;
         mIsDeleted = false;
         mMode = 0;
-        mWidgetType = Notes.TYPE_WIDGET_INVALIDE;
+        mWidgetType = Notes.TYPE_WIDGET_INVALIDE;  // 默认无效小部件类型
     }
 
-    // Existing note construct
+    // 构造函数：加载已有笔记
     private WorkingNote(Context context, long noteId, long folderId) {
         mContext = context;
         mNoteId = noteId;
         mFolderId = folderId;
         mIsDeleted = false;
         mNote = new Note();
-        loadNote();
+        loadNote();  // 加载笔记数据
     }
 
+    // 加载笔记主信息
     private void loadNote() {
+        // 查询笔记主表数据
         Cursor cursor = mContext.getContentResolver().query(
                 ContentUris.withAppendedId(Notes.CONTENT_NOTE_URI, mNoteId), NOTE_PROJECTION, null,
                 null, null);
 
         if (cursor != null) {
             if (cursor.moveToFirst()) {
+                // 从游标中读取数据
                 mFolderId = cursor.getLong(NOTE_PARENT_ID_COLUMN);
                 mBgColorId = cursor.getInt(NOTE_BG_COLOR_ID_COLUMN);
                 mWidgetId = cursor.getInt(NOTE_WIDGET_ID_COLUMN);
@@ -140,13 +148,15 @@ public class WorkingNote {
             }
             cursor.close();
         } else {
-            Log.e(TAG, "No note with id:" + mNoteId);
-            throw new IllegalArgumentException("Unable to find note with id " + mNoteId);
+            Log.e(TAG, "未找到ID为:" + mNoteId + "的笔记");
+            throw new IllegalArgumentException("无法找到ID为 " + mNoteId + " 的笔记");
         }
-        loadNoteData();
+        loadNoteData();  // 加载笔记详情数据
     }
 
+    // 加载笔记详情数据
     private void loadNoteData() {
+        // 查询笔记详情数据
         Cursor cursor = mContext.getContentResolver().query(Notes.CONTENT_DATA_URI, DATA_PROJECTION,
                 DataColumns.NOTE_ID + "=?", new String[] {
                     String.valueOf(mNoteId)
@@ -156,51 +166,53 @@ public class WorkingNote {
             if (cursor.moveToFirst()) {
                 do {
                     String type = cursor.getString(DATA_MIME_TYPE_COLUMN);
-                    if (DataConstants.NOTE.equals(type)) {
+                    if (DataConstants.NOTE.equals(type)) {  // 文本类型笔记
                         mContent = cursor.getString(DATA_CONTENT_COLUMN);
                         mMode = cursor.getInt(DATA_MODE_COLUMN);
                         mNote.setTextDataId(cursor.getLong(DATA_ID_COLUMN));
-                    } else if (DataConstants.CALL_NOTE.equals(type)) {
+                    } else if (DataConstants.CALL_NOTE.equals(type)) {  // 通话记录类型笔记
                         mNote.setCallDataId(cursor.getLong(DATA_ID_COLUMN));
                     } else {
-                        Log.d(TAG, "Wrong note type with type:" + type);
+                        Log.d(TAG, "未知笔记类型:" + type);
                     }
                 } while (cursor.moveToNext());
             }
             cursor.close();
         } else {
-            Log.e(TAG, "No data with id:" + mNoteId);
-            throw new IllegalArgumentException("Unable to find note's data with id " + mNoteId);
+            Log.e(TAG, "未找到ID为:" + mNoteId + "的笔记数据");
+            throw new IllegalArgumentException("无法找到ID为 " + mNoteId + " 的笔记数据");
         }
     }
 
+    // 创建空笔记（静态工厂方法）
     public static WorkingNote createEmptyNote(Context context, long folderId, int widgetId,
             int widgetType, int defaultBgColorId) {
         WorkingNote note = new WorkingNote(context, folderId);
-        note.setBgColorId(defaultBgColorId);
-        note.setWidgetId(widgetId);
-        note.setWidgetType(widgetType);
+        note.setBgColorId(defaultBgColorId);  // 设置默认背景色
+        note.setWidgetId(widgetId);           // 设置小部件ID
+        note.setWidgetType(widgetType);       // 设置小部件类型
         return note;
     }
 
+    // 加载已有笔记（静态工厂方法）
     public static WorkingNote load(Context context, long id) {
         return new WorkingNote(context, id, 0);
     }
 
+    // 保存笔记（同步方法）
     public synchronized boolean saveNote() {
-        if (isWorthSaving()) {
-            if (!existInDatabase()) {
+        if (isWorthSaving()) {  // 检查是否值得保存
+            if (!existInDatabase()) {  // 如果数据库中不存在则创建新ID
                 if ((mNoteId = Note.getNewNoteId(mContext, mFolderId)) == 0) {
-                    Log.e(TAG, "Create new note fail with id:" + mNoteId);
+                    Log.e(TAG, "创建新笔记失败，ID:" + mNoteId);
                     return false;
                 }
             }
 
+            // 同步笔记数据到数据库
             mNote.syncNote(mContext, mNoteId);
 
-            /**
-             * Update widget content if there exist any widget of this note
-             */
+            // 如果有关联的小部件，更新小部件内容
             if (mWidgetId != AppWidgetManager.INVALID_APPWIDGET_ID
                     && mWidgetType != Notes.TYPE_WIDGET_INVALIDE
                     && mNoteSettingStatusListener != null) {
@@ -212,11 +224,17 @@ public class WorkingNote {
         }
     }
 
+    // 检查笔记是否存在于数据库
     public boolean existInDatabase() {
         return mNoteId > 0;
     }
 
+    // 检查笔记是否值得保存
     private boolean isWorthSaving() {
+        // 以下情况不值得保存：
+        // 1. 已被删除
+        // 2. 新笔记但内容为空
+        // 3. 已有笔记但未修改
         if (mIsDeleted || (!existInDatabase() && TextUtils.isEmpty(mContent))
                 || (existInDatabase() && !mNote.isLocalModified())) {
             return false;
@@ -225,31 +243,38 @@ public class WorkingNote {
         }
     }
 
+    // 设置设置变更监听器
     public void setOnSettingStatusChangedListener(NoteSettingChangedListener l) {
         mNoteSettingStatusListener = l;
     }
 
+    // 设置提醒日期
     public void setAlertDate(long date, boolean set) {
         if (date != mAlertDate) {
             mAlertDate = date;
             mNote.setNoteValue(NoteColumns.ALERTED_DATE, String.valueOf(mAlertDate));
         }
+        // 通知监听器提醒时间已变更
         if (mNoteSettingStatusListener != null) {
             mNoteSettingStatusListener.onClockAlertChanged(date, set);
         }
     }
 
+    // 标记为已删除
     public void markDeleted(boolean mark) {
         mIsDeleted = mark;
+        // 如果有关联的小部件，更新小部件
         if (mWidgetId != AppWidgetManager.INVALID_APPWIDGET_ID
                 && mWidgetType != Notes.TYPE_WIDGET_INVALIDE && mNoteSettingStatusListener != null) {
                 mNoteSettingStatusListener.onWidgetChanged();
         }
     }
 
+    // 设置背景颜色
     public void setBgColorId(int id) {
         if (id != mBgColorId) {
             mBgColorId = id;
+            // 通知监听器背景色已变更
             if (mNoteSettingStatusListener != null) {
                 mNoteSettingStatusListener.onBackgroundColorChanged();
             }
@@ -257,8 +282,10 @@ public class WorkingNote {
         }
     }
 
+    // 设置清单模式
     public void setCheckListMode(int mode) {
         if (mMode != mode) {
+            // 通知监听器模式变更
             if (mNoteSettingStatusListener != null) {
                 mNoteSettingStatusListener.onCheckListModeChanged(mMode, mode);
             }
@@ -267,6 +294,7 @@ public class WorkingNote {
         }
     }
 
+    // 设置小部件类型
     public void setWidgetType(int type) {
         if (type != mWidgetType) {
             mWidgetType = type;
@@ -274,6 +302,7 @@ public class WorkingNote {
         }
     }
 
+    // 设置小部件ID
     public void setWidgetId(int id) {
         if (id != mWidgetId) {
             mWidgetId = id;
@@ -281,6 +310,7 @@ public class WorkingNote {
         }
     }
 
+    // 设置笔记内容
     public void setWorkingText(String text) {
         if (!TextUtils.equals(mContent, text)) {
             mContent = text;
@@ -288,81 +318,97 @@ public class WorkingNote {
         }
     }
 
+    // 转换为通话记录笔记
     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));
     }
 
+    // 检查是否有提醒
     public boolean hasClockAlert() {
         return (mAlertDate > 0 ? true : false);
     }
 
+    // 获取笔记内容
     public String getContent() {
         return mContent;
     }
 
+    // 获取提醒日期
     public long getAlertDate() {
         return mAlertDate;
     }
 
+    // 获取修改日期
     public long getModifiedDate() {
         return mModifiedDate;
     }
 
+    // 获取背景颜色资源ID
     public int getBgColorResId() {
         return NoteBgResources.getNoteBgResource(mBgColorId);
     }
 
+    // 获取背景颜色ID
     public int getBgColorId() {
         return mBgColorId;
     }
 
+    // 获取标题背景资源ID
     public int getTitleBgResId() {
         return NoteBgResources.getNoteTitleBgResource(mBgColorId);
     }
 
+    // 获取当前模式
     public int getCheckListMode() {
         return mMode;
     }
 
+    // 获取笔记ID
     public long getNoteId() {
         return mNoteId;
     }
 
+    // 获取文件夹ID
     public long getFolderId() {
         return mFolderId;
     }
 
+    // 获取小部件ID
     public int getWidgetId() {
         return mWidgetId;
     }
 
+    // 获取小部件类型
     public int getWidgetType() {
         return mWidgetType;
     }
 
+    // 笔记设置变更监听器接口
     public interface NoteSettingChangedListener {
         /**
-         * Called when the background color of current note has just changed
+         * 当笔记背景色变更时调用
          */
         void onBackgroundColorChanged();
 
         /**
-         * Called when user set clock
+         * 当设置提醒时间时调用
+         * @param date 提醒时间
+         * @param set 是否设置
          */
         void onClockAlertChanged(long date, boolean set);
 
         /**
-         * Call when user create note from widget
+         * 当从小部件创建笔记时调用
          */
         void onWidgetChanged();
 
         /**
-         * Call when switch between check list mode and normal mode
-         * @param oldMode is previous mode before change
-         * @param newMode is new mode
+         * 当切换清单模式时调用
+         * @param oldMode 切换前的模式
+         * @param newMode 切换后的模式
          */
         void onCheckListModeChanged(int oldMode, int newMode);
     }
-}
+}