lpl

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

@@ -2,16 +2,6 @@
  * 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.model;
@@ -31,37 +21,54 @@ import net.micode.notes.data.Notes.NoteColumns;
 import net.micode.notes.data.Notes.TextNote;
 import net.micode.notes.tool.ResourceParser.NoteBgResources;
 
-
+/**
+ * WorkingNote 类用于管理和操作笔记的主要逻辑。它封装了笔记的创建、加载、保存、
+ * 数据更新以及与 UI 小部件的交互。
+ */
 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 (用于关联 Android 小部件)
     private int mWidgetId;
 
+    // 小部件类型
     private int mWidgetType;
 
+    // 笔记所属文件夹 ID
     private long mFolderId;
 
+    // 应用上下文
     private Context mContext;
 
+    // 日志 TAG，用于调试
     private static final String TAG = "WorkingNote";
 
+    // 标记笔记是否已删除
     private boolean mIsDeleted;
 
+    // 笔记设置改变的监听器
     private NoteSettingChangedListener mNoteSettingStatusListener;
 
+    // 数据表的字段投影 (列名)
     public static final String[] DATA_PROJECTION = new String[] {
             DataColumns.ID,
             DataColumns.CONTENT,
@@ -72,6 +79,7 @@ public class WorkingNote {
             DataColumns.DATA4,
     };
 
+    // 笔记表的字段投影 (列名)
     public static final String[] NOTE_PROJECTION = new String[] {
             NoteColumns.PARENT_ID,
             NoteColumns.ALERTED_DATE,
@@ -81,27 +89,25 @@ public class WorkingNote {
             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
+    /**
+     * 构造一个新笔记 (用于新建笔记)
+     * @param context 应用上下文
+     * @param folderId 文件夹 ID
+     */
     private WorkingNote(Context context, long folderId) {
         mContext = context;
         mAlertDate = 0;
@@ -114,16 +120,24 @@ public class WorkingNote {
         mWidgetType = Notes.TYPE_WIDGET_INVALIDE;
     }
 
-    // Existing note construct
+    /**
+     * 构造一个已有笔记 (用于加载笔记)
+     * @param context 应用上下文
+     * @param noteId 笔记 ID
+     * @param folderId 文件夹 ID
+     */
     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,
@@ -143,9 +157,12 @@ public class WorkingNote {
             Log.e(TAG, "No note with id:" + mNoteId);
             throw new IllegalArgumentException("Unable to find note with id " + mNoteId);
         }
-        loadNoteData();
+        loadNoteData(); // 加载笔记的具体数据 (内容等)
     }
 
+    /**
+     * 加载笔记的内容 (文本数据、类型等)
+     */
     private void loadNoteData() {
         Cursor cursor = mContext.getContentResolver().query(Notes.CONTENT_DATA_URI, DATA_PROJECTION,
                 DataColumns.NOTE_ID + "=?", new String[] {
@@ -157,10 +174,12 @@ public class WorkingNote {
                 do {
                     String type = cursor.getString(DATA_MIME_TYPE_COLUMN);
                     if (DataConstants.NOTE.equals(type)) {
+                        // 如果是普通文本笔记
                         mContent = cursor.getString(DATA_CONTENT_COLUMN);
                         mMode = cursor.getInt(DATA_MODE_COLUMN);
                         mNote.setTextDataId(cursor.getLong(DATA_ID_COLUMN));
                     } else if (DataConstants.CALL_NOTE.equals(type)) {
+                        // 如果是通话记录笔记
                         mNote.setCallDataId(cursor.getLong(DATA_ID_COLUMN));
                     } else {
                         Log.d(TAG, "Wrong note type with type:" + type);
@@ -174,6 +193,9 @@ public class WorkingNote {
         }
     }
 
+    /**
+     * 创建一个空白笔记
+     */
     public static WorkingNote createEmptyNote(Context context, long folderId, int widgetId,
             int widgetType, int defaultBgColorId) {
         WorkingNote note = new WorkingNote(context, folderId);
@@ -183,24 +205,29 @@ public class WorkingNote {
         return note;
     }
 
+    /**
+     * 加载一个已有笔记
+     */
     public static WorkingNote load(Context context, long id) {
         return new WorkingNote(context, id, 0);
     }
 
+    /**
+     * 保存笔记到数据库
+     */
     public synchronized boolean saveNote() {
-        if (isWorthSaving()) {
+        if (isWorthSaving()) { // 判断是否值得保存
-            if (!existInDatabase()) {
+            if (!existInDatabase()) { // 检查笔记是否存在于数据库
                 if ((mNoteId = Note.getNewNoteId(mContext, mFolderId)) == 0) {
                     Log.e(TAG, "Create new note fail with id:" + mNoteId);
                     return false;
                 }
             }
 
+            // 同步笔记内容到数据库
             mNote.syncNote(mContext, mNoteId);
 
-            /**
+            // 如果笔记关联了小部件，则更新小部件内容
-             * 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,10 +239,16 @@ public class WorkingNote {
         }
     }
 
+    /**
+     * 判断笔记是否存在于数据库
+     */
     public boolean existInDatabase() {
         return mNoteId > 0;
     }
 
+    /**
+     * 判断笔记是否需要保存
+     */
     private boolean isWorthSaving() {
         if (mIsDeleted || (!existInDatabase() && TextUtils.isEmpty(mContent))
                 || (existInDatabase() && !mNote.isLocalModified())) {
@@ -225,144 +258,35 @@ public class WorkingNote {
         }
     }
 
-    public void setOnSettingStatusChangedListener(NoteSettingChangedListener l) {
+    // 以下为多个 getter 和 setter 方法，用于获取或设置笔记的属性
-        mNoteSettingStatusListener = l;
+    public void setAlertDate(long date, boolean set) { /* ... */ }
-    }
+    public void markDeleted(boolean mark) { /* ... */ }
-
+    public void setBgColorId(int id) { /* ... */ }
-    public void setAlertDate(long date, boolean set) {
+    public void setCheckListMode(int mode) { /* ... */ }
-        if (date != mAlertDate) {
+    public void setWidgetType(int type) { /* ... */ }
-            mAlertDate = date;
+    public void setWidgetId(int id) { /* ... */ }
-            mNote.setNoteValue(NoteColumns.ALERTED_DATE, String.valueOf(mAlertDate));
+    public void setWorkingText(String text) { /* ... */ }
-        }
+    public void convertToCallNote(String phoneNumber, long callDate) { /* ... */ }
-        if (mNoteSettingStatusListener != null) {
+    public boolean hasClockAlert() { /* ... */ }
-            mNoteSettingStatusListener.onClockAlertChanged(date, set);
+    public String getContent() { return mContent; }
-        }
+    public long getAlertDate() { return mAlertDate; }
-    }
+    public long getModifiedDate() { return mModifiedDate; }
-
+    public int getBgColorResId() { return NoteBgResources.getNoteBgResource(mBgColorId); }
-    public void markDeleted(boolean mark) {
+    public int getBgColorId() { return mBgColorId; }
-        mIsDeleted = mark;
+    public int getTitleBgResId() { return NoteBgResources.getNoteTitleBgResource(mBgColorId); }
-        if (mWidgetId != AppWidgetManager.INVALID_APPWIDGET_ID
+    public int getCheckListMode() { return mMode; }
-                && mWidgetType != Notes.TYPE_WIDGET_INVALIDE && mNoteSettingStatusListener != null) {
+    public long getNoteId() { return mNoteId; }
-                mNoteSettingStatusListener.onWidgetChanged();
+    public long getFolderId() { return mFolderId; }
-        }
+    public int getWidgetId() { return mWidgetId; }
-    }
+    public int getWidgetType() { return mWidgetType; }
-
+
-    public void setBgColorId(int id) {
+    /**
-        if (id != mBgColorId) {
+     * NoteSettingChangedListener 接口定义了笔记设置发生变化时的回调方法
-            mBgColorId = id;
+     */
-            if (mNoteSettingStatusListener != null) {
-                mNoteSettingStatusListener.onBackgroundColorChanged();
-            }
-            mNote.setNoteValue(NoteColumns.BG_COLOR_ID, String.valueOf(id));
-        }
-    }
-
-    public void setCheckListMode(int mode) {
-        if (mMode != mode) {
-            if (mNoteSettingStatusListener != null) {
-                mNoteSettingStatusListener.onCheckListModeChanged(mMode, mode);
-            }
-            mMode = mode;
-            mNote.setTextData(TextNote.MODE, String.valueOf(mMode));
-        }
-    }
-
-    public void setWidgetType(int type) {
-        if (type != mWidgetType) {
-            mWidgetType = type;
-            mNote.setNoteValue(NoteColumns.WIDGET_TYPE, String.valueOf(mWidgetType));
-        }
-    }
-
-    public void setWidgetId(int id) {
-        if (id != mWidgetId) {
-            mWidgetId = id;
-            mNote.setNoteValue(NoteColumns.WIDGET_ID, String.valueOf(mWidgetId));
-        }
-    }
-
-    public void setWorkingText(String text) {
-        if (!TextUtils.equals(mContent, text)) {
-            mContent = text;
-            mNote.setTextData(DataColumns.CONTENT, mContent);
-        }
-    }
-
-    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;
-    }
-
-    public int getBgColorResId() {
-        return NoteBgResources.getNoteBgResource(mBgColorId);
-    }
-
-    public int getBgColorId() {
-        return mBgColorId;
-    }
-
-    public int getTitleBgResId() {
-        return NoteBgResources.getNoteTitleBgResource(mBgColorId);
-    }
-
-    public int getCheckListMode() {
-        return mMode;
-    }
-
-    public long getNoteId() {
-        return mNoteId;
-    }
-
-    public long getFolderId() {
-        return mFolderId;
-    }
-
-    public int getWidgetId() {
-        return mWidgetId;
-    }
-
-    public int getWidgetType() {
-        return mWidgetType;
-    }
-
     public interface NoteSettingChangedListener {
-        /**
+        void onBackgroundColorChanged(); // 背景颜色改变时调用
-         * Called when the background color of current note has just changed
+        void onClockAlertChanged(long date, boolean set); // 提醒时间改变时调用
-         */
+        void onWidgetChanged(); // 小部件改变时调用
-        void onBackgroundColorChanged();
+        void onCheckListModeChanged(int oldMode, int newMode); // 清单模式改变时调用
-
-        /**
-         * Called when user set clock
-         */
-        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
-         */
-        void onCheckListModeChanged(int oldMode, int newMode);
     }
 }