Update WorkingNote.java

src/Notes-master/src/net/micode/notes/model/WorkingNote.java

@@ -1,21 +1,4 @@
-/*
- * 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;
-
 import android.appwidget.AppWidgetManager;
 import android.content.ContentUris;
 import android.content.Context;
@@ -31,37 +14,39 @@ import net.micode.notes.data.Notes.NoteColumns;
 import net.micode.notes.data.Notes.TextNote;
 import net.micode.notes.tool.ResourceParser.NoteBgResources;
 
-
+// WorkingNote类，用于处理正在操作（编辑、修改等）的笔记相关业务逻辑
 public class WorkingNote {
-    // Note for the working note
+
+    // 关联的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;
-
+    // 与该笔记关联的小部件（Widget）的ID，用于在桌面等展示的组件相关标识
     private int mWidgetId;
-
+    // 小部件的类型，可能有不同种类的小部件对应不同的展示或功能形式
     private int mWidgetType;
-
+    // 笔记所属文件夹的ID，用于对笔记进行分类管理
     private long mFolderId;
-
+    // 应用上下文，用于获取ContentResolver等操作数据库相关资源以及其他系统相关操作
     private Context mContext;
-
+    // 用于日志记录的标签，方便在Log输出中识别是这个类相关的日志信息
     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 +57,7 @@ public class WorkingNote {
             DataColumns.DATA4,
     };
 
+    // 定义查询笔记基本信息时的投影数组，指定要从数据库中获取的列名，用于获取笔记的如父文件夹ID、提醒日期等基本属性信息
     public static final String[] NOTE_PROJECTION = new String[] {
             NoteColumns.PARENT_ID,
             NoteColumns.ALERTED_DATE,
@@ -81,56 +67,69 @@ public class WorkingNote {
             NoteColumns.MODIFIED_DATE
     };
 
+    // 对应DATA_PROJECTION数组中数据ID列的索引，方便从查询结果的Cursor中获取对应数据
     private static final int DATA_ID_COLUMN = 0;
-
+    // 对应DATA_PROJECTION数组中内容列的索引，方便从查询结果的Cursor中获取笔记内容数据
     private static final int DATA_CONTENT_COLUMN = 1;
-
+    // 对应DATA_PROJECTION数组中MIME类型列的索引，方便从查询结果的Cursor中获取笔记数据的MIME类型信息
     private static final int DATA_MIME_TYPE_COLUMN = 2;
-
+    // 对应DATA_PROJECTION数组中模式列的索引，方便从查询结果的Cursor中获取笔记的模式相关信息
     private static final int DATA_MODE_COLUMN = 3;
 
+    // 对应NOTE_PROJECTION数组中父文件夹ID列的索引，方便从查询结果的Cursor中获取笔记所属文件夹的ID信息
     private static final int NOTE_PARENT_ID_COLUMN = 0;
-
+    // 对应NOTE_PROJECTION数组中提醒日期列的索引，方便从查询结果的Cursor中获取笔记的提醒日期信息
     private static final int NOTE_ALERTED_DATE_COLUMN = 1;
-
+    // 对应NOTE_PROJECTION数组中背景颜色ID列的索引，方便从查询结果的Cursor中获取笔记的背景颜色ID信息
     private static final int NOTE_BG_COLOR_ID_COLUMN = 2;
-
+    // 对应NOTE_PROJECTION数组中小部件ID列的索引，方便从查询结果的Cursor中获取与笔记关联的小部件ID信息
     private static final int NOTE_WIDGET_ID_COLUMN = 3;
-
+    // 对应NOTE_PROJECTION数组中小部件类型列的索引，方便从查询结果的Cursor中获取小部件的类型信息
     private static final int NOTE_WIDGET_TYPE_COLUMN = 4;
-
+    // 对应NOTE_PROJECTION数组中修改日期列的索引，方便从查询结果的Cursor中获取笔记的最后修改日期信息
     private static final int NOTE_MODIFIED_DATE_COLUMN = 5;
 
-    // New note construct
+    // 构造函数，用于创建一个新的空笔记（尚未保存到数据库的情况），初始化相关属性值
     private WorkingNote(Context context, long folderId) {
         mContext = context;
+        // 初始提醒日期设为0，表示没有设置提醒
         mAlertDate = 0;
+        // 设置初始修改日期为当前系统时间，作为创建时间和初始修改时间
         mModifiedDate = System.currentTimeMillis();
         mFolderId = folderId;
+        // 创建一个Note对象，用于后续处理笔记相关操作
         mNote = new Note();
+        // 新笔记的ID初始设为0，待保存时获取实际的ID
         mNoteId = 0;
+        // 标记笔记初始未被删除
         mIsDeleted = false;
+        // 初始模式设为0，具体含义根据业务逻辑而定
         mMode = 0;
+        // 初始小部件类型设为无效类型（根据Notes.TYPE_WIDGET_INVALIDE的定义），表示未关联有效小部件
         mWidgetType = Notes.TYPE_WIDGET_INVALIDE;
     }
 
-    // Existing note construct
+    // 构造函数，用于加载已存在的笔记（通过笔记ID来加载其相关信息），初始化相关属性并从数据库读取数据
     private WorkingNote(Context context, long noteId, long folderId) {
         mContext = context;
         mNoteId = noteId;
         mFolderId = folderId;
         mIsDeleted = false;
         mNote = new Note();
+        // 调用方法从数据库加载笔记的详细信息
         loadNote();
     }
 
+    // 从数据库中加载笔记的基本信息（如所属文件夹ID、背景颜色ID等），通过ContentResolver查询数据库并解析结果
     private void loadNote() {
+        // 通过ContentResolver查询指定笔记ID对应的笔记基本信息，使用预定义的NOTE_PROJECTION指定要获取的列
         Cursor cursor = mContext.getContentResolver().query(
                 ContentUris.withAppendedId(Notes.CONTENT_NOTE_URI, mNoteId), NOTE_PROJECTION, null,
                 null, null);
 
-        if (cursor != null) {
+        if (cursor!= null) {
             if (cursor.moveToFirst()) {
+                // 从查询结果的Cursor中获取对应列的数据，赋值给相应的属性，比如获取文件夹ID、背景颜色ID等信息
                 mFolderId = cursor.getLong(NOTE_PARENT_ID_COLUMN);
                 mBgColorId = cursor.getInt(NOTE_BG_COLOR_ID_COLUMN);
                 mWidgetId = cursor.getInt(NOTE_WIDGET_ID_COLUMN);
@@ -138,42 +137,54 @@ public class WorkingNote {
                 mAlertDate = cursor.getLong(NOTE_ALERTED_DATE_COLUMN);
                 mModifiedDate = cursor.getLong(NOTE_MODIFIED_DATE_COLUMN);
             }
+            // 关闭Cursor，释放资源
             cursor.close();
         } else {
+            // 如果查询结果为null，说明没有找到对应的笔记，记录错误日志并抛出异常，表示无法找到该ID的笔记
             Log.e(TAG, "No note with id:" + mNoteId);
             throw new IllegalArgumentException("Unable to find note with id " + mNoteId);
         }
+        // 加载完笔记基本信息后，继续加载笔记的数据信息（如内容、模式等）
         loadNoteData();
     }
 
+    // 从数据库中加载笔记的数据信息（如内容、模式以及关联的数据ID等），通过ContentResolver查询数据库并解析结果
     private void loadNoteData() {
+        // 通过ContentResolver查询指定笔记ID对应的笔记数据信息
         Cursor cursor = mContext.getContentResolver().query(Notes.CONTENT_DATA_URI, DATA_PROJECTION,
                 DataColumns.NOTE_ID + "=?", new String[] {
                     String.valueOf(mNoteId)
                 }, null);
 
-        if (cursor != null) {
+        if (cursor!= null) {
             if (cursor.moveToFirst()) {
                 do {
+                    // 获取数据的MIME类型，用于判断是哪种类型的数据（比如文本笔记、通话笔记等）
                     String type = cursor.getString(DATA_MIME_TYPE_COLUMN);
                     if (DataConstants.NOTE.equals(type)) {
+                        // 如果是普通笔记类型，获取笔记内容、模式信息，并设置笔记关联的文本数据ID
                         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)) {
+                        // 如果是通话笔记类型，设置笔记关联的通话数据ID
                         mNote.setCallDataId(cursor.getLong(DATA_ID_COLUMN));
                     } else {
+                        // 如果是其他未知类型，记录调试日志，提示出现了错误的笔记类型
                         Log.d(TAG, "Wrong note type with type:" + type);
                     }
                 } while (cursor.moveToNext());
             }
+            // 关闭Cursor，释放资源
             cursor.close();
         } else {
+            // 如果查询结果为null，说明没有找到对应笔记的数据，记录错误日志并抛出异常，表示无法找到该ID笔记的数据
             Log.e(TAG, "No data with id:" + mNoteId);
             throw new IllegalArgumentException("Unable to find note's data with id " + mNoteId);
         }
     }
 
+    // 用于创建一个新的空笔记对象，并设置一些初始属性（如背景颜色ID、小部件ID和类型等）
     public static WorkingNote createEmptyNote(Context context, long folderId, int widgetId,
             int widgetType, int defaultBgColorId) {
         WorkingNote note = new WorkingNote(context, folderId);
@@ -183,27 +194,32 @@ public class WorkingNote {
         return note;
     }
 
+    // 用于加载指定ID的已存在笔记对象
     public static WorkingNote load(Context context, long id) {
         return new WorkingNote(context, id, 0);
     }
 
+    // 同步保存笔记的方法，判断笔记是否值得保存（有修改等情况），如果不存在则创建新笔记ID，然后同步笔记数据到数据库
     public synchronized boolean saveNote() {
         if (isWorthSaving()) {
             if (!existInDatabase()) {
+                // 如果笔记不存在于数据库中，调用Note类的方法获取新的笔记ID，若获取失败则记录错误日志并返回false
                 if ((mNoteId = Note.getNewNoteId(mContext, mFolderId)) == 0) {
                     Log.e(TAG, "Create new note fail with id:" + mNoteId);
                     return false;
                 }
             }
 
+            // 调用Note对象的方法同步笔记数据到数据库
             mNote.syncNote(mContext, mNoteId);
 
             /**
-             * Update widget content if there exist any widget of this note
+             * 如果存在与该笔记关联的小部件（小部件ID有效且小部件类型有效），并且设置了笔记设置状态监听器
+             * 则触发监听器的小部件改变回调方法，用于更新小部件展示内容等相关操作
              */
-            if (mWidgetId != AppWidgetManager.INVALID_APPWIDGET_ID
+            if (mWidgetId!= AppWidgetManager.INVALID_APPWIDGET_ID
-                    && mWidgetType != Notes.TYPE_WIDGET_INVALIDE
+                    && mWidgetType!= Notes.TYPE_WIDGET_INVALIDE
-                    && mNoteSettingStatusListener != null) {
+                    && mNoteSettingStatusListener!= null) {
                 mNoteSettingStatusListener.onWidgetChanged();
             }
             return true;
@@ -212,54 +228,61 @@ public class WorkingNote {
         }
     }
 
+    // 判断笔记是否已存在于数据库中，通过检查笔记ID是否大于0来判断
     public boolean existInDatabase() {
         return mNoteId > 0;
     }
 
+    // 判断笔记是否值得保存，根据是否已删除、内容是否为空（新笔记情况）、是否有本地修改（已存在笔记情况）等条件来判断
     private boolean isWorthSaving() {
         if (mIsDeleted || (!existInDatabase() && TextUtils.isEmpty(mContent))
-                || (existInDatabase() && !mNote.isLocalModified())) {
+                || (existInDatabase() &&!mNote.isLocalModified())) {
             return false;
         } else {
             return true;
         }
     }
 
+    // 设置笔记设置状态变化的监听器，用于监听笔记相关属性改变时的回调通知
     public void setOnSettingStatusChangedListener(NoteSettingChangedListener l) {
         mNoteSettingStatusListener = l;
     }
 
+    // 设置笔记的提醒日期，同时根据日期是否改变以及是否设置了监听器来触发相应的监听器回调方法
     public void setAlertDate(long date, boolean set) {
-        if (date != mAlertDate) {
+        if (date!= mAlertDate) {
             mAlertDate = date;
             mNote.setNoteValue(NoteColumns.ALERTED_DATE, String.valueOf(mAlertDate));
         }
-        if (mNoteSettingStatusListener != null) {
+        if (mNoteSettingStatusListener!= null) {
             mNoteSettingStatusListener.onClockAlertChanged(date, set);
         }
     }
 
+    // 标记笔记是否已删除，同时根据小部件相关情况以及是否设置了监听器来触发相应的监听器回调方法
     public void markDeleted(boolean mark) {
         mIsDeleted = mark;
-        if (mWidgetId != AppWidgetManager.INVALID_APPWIDGET_ID
+        if (mWidgetId!= AppWidgetManager.INVALID_APPWIDGET_ID
-                && mWidgetType != Notes.TYPE_WIDGET_INVALIDE && mNoteSettingStatusListener != null) {
+                && mWidgetType!= Notes.TYPE_WIDGET_INVALIDE && mNoteSettingStatusListener!= null) {
                 mNoteSettingStatusListener.onWidgetChanged();
         }
     }
 
+    // 设置笔记的背景颜色ID，同时根据颜色ID是否改变以及是否设置了监听器来触发相应的监听器回调方法，并更新笔记对应属性值
     public void setBgColorId(int id) {
-        if (id != mBgColorId) {
+        if (id!= mBgColorId) {
             mBgColorId = id;
-            if (mNoteSettingStatusListener != null) {
+            if (mNoteSettingStatusListener!= null) {
                 mNoteSettingStatusListener.onBackgroundColorChanged();
             }
             mNote.setNoteValue(NoteColumns.BG_COLOR_ID, String.valueOf(id));
         }
     }
 
+    // 设置笔记的清单模式（比如切换清单模式和普通模式），同时根据模式是否改变以及是否设置了监听器来触发相应的监听器回调方法，并更新笔记对应属性值
     public void setCheckListMode(int mode) {
-        if (mMode != mode) {
+        if (mMode!= mode) {
-            if (mNoteSettingStatusListener != null) {
+            if (mNoteSettingStatusListener!= null) {
                 mNoteSettingStatusListener.onCheckListModeChanged(mMode, mode);
             }
             mMode = mode;
@@ -267,20 +290,23 @@ public class WorkingNote {
         }
     }
 
+    // 设置笔记关联的小部件类型，根据类型是否改变来更新笔记对应属性值
     public void setWidgetType(int type) {
-        if (type != mWidgetType) {
+        if (type!= mWidgetType) {
             mWidgetType = type;
             mNote.setNoteValue(NoteColumns.WIDGET_TYPE, String.valueOf(mWidgetType));
         }
     }
 
+    // 设置笔记关联的小部件ID，根据ID是否改变来更新笔记对应属性值
     public void setWidgetId(int id) {
-        if (id != mWidgetId) {
+        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;
@@ -288,81 +314,96 @@ public class WorkingNote {
         }
     }
 
+    // 将笔记转换为通话笔记类型，设置通话相关的数据（如通话日期、电话号码等）以及笔记所属文件夹ID
     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));
     }
 
+    // 判断笔记是否设置了时钟提醒，通过检查提醒日期是否大于0来判断
     public boolean hasClockAlert() {
-        return (mAlertDate > 0 ? true : false);
+        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);
     }
+    // 该方法用于获取笔记的内容，返回值为String类型，通常代表笔记中所包含的具体文本信息
+public String getContent() {
+    return mContent;
+}
+// 获取笔记设置的提醒日期，返回值为long类型，可用于后续与时间相关的判断或操作
+public long getAlertDate() {
+    return mAlertDate;
+}
 
-    public int getBgColorId() {
+// 获取笔记最后修改的日期，返回值为long类型，有助于记录笔记的修改历史情况
-        return mBgColorId;
+public long getModifiedDate() {
-    }
+    return mModifiedDate;
+}
+// 返回的int类型的资源ID可用于在界面渲染等场景中正确设置笔记的背景颜色资源
+public int getBgColorResId() {
+    return NoteBgResources.getNoteBgResource(mBgColorId);
+}
 
-    public int getTitleBgResId() {
+// 直接返回笔记背景颜色的标识（mBgColorId），返回值为int类型，在内部用于区分不同的背景颜色配置
-        return NoteBgResources.getNoteTitleBgResource(mBgColorId);
+public int getBgColorId() {
-    }
+    return mBgColorId;
+}
 
-    public int getCheckListMode() {
+// 获取笔记标题背景对应的资源ID，借助NoteBgResources类的静态方法，传入背景颜色标识（mBgColorId）来获取相应资源ID
-        return mMode;
+// 得到的int类型的资源ID用于在界面上准确设置笔记标题部分的背景资源显示
-    }
+public int getTitleBgResId() {
+    return NoteBgResources.getNoteTitleBgResource(mBgColorId);
+}
 
-    public long getNoteId() {
+// 获取笔记所处的清单模式状态值，返回值为int类型，可用于判断笔记当前是处于普通模式还是如勾选清单等特定模式
-        return mNoteId;
+public int getCheckListMode() {
-    }
+    return mMode;
+}
 
-    public long getFolderId() {
+// 获取笔记的唯一标识符，返回值为long类型，该ID在整个笔记管理系统中可用于唯一确定这个笔记，方便进行查找、关联等操作
-        return mFolderId;
+public long getNoteId() {
-    }
+    return mNoteId;
+}
 
-    public int getWidgetId() {
+// 获取笔记所属文件夹的标识符，返回值为long类型，有助于对笔记按照文件夹进行分类管理，确定其归属关系
-        return mWidgetId;
+public long getFolderId() {
-    }
+    return mFolderId;
+}
 
-    public int getWidgetType() {
+// 获取与笔记相关的小部件的标识符，返回值为int类型，在涉及桌面小部件等功能场景下，用于区分不同的小部件实例
-        return mWidgetType;
+public int getWidgetId() {
-    }
+    return mWidgetId;
+}
 
-    public interface NoteSettingChangedListener {
+// 获取小部件的类型，返回值为int类型，不同的小部件类型可能对应不同的显示样式或功能逻辑，方便进行相应的处理
-        /**
+public int getWidgetType() {
-         * Called when the background color of current note has just changed
+    return mWidgetType;
-         */
-        void onBackgroundColorChanged();
-
-        /**
-         * 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);
-    }
 }
+
+// 定义了一个名为NoteSettingChangedListener的接口，用于监听笔记相关设置发生改变的情况，并定义了相应的回调方法
+public interface NoteSettingChangedListener {
+
+    /**
+      当笔记当前的背景颜色发生改变时，方法会被调用
+     *更新笔记在界面上显示的背景颜色效果
+     */
+    void onBackgroundColorChanged();
+
+    /**
+     * 当用户设置时钟提醒时，方法会被调用
+     * @param date 传入的long类型参数，表示提醒对应的时间日期值，可用于后续根据具体时间进行相应逻辑处理
+     * @param set 传入的boolean类型参数，用于表明是设置（true）还是取消（false）提醒操作，方便根据不同情况执行不同逻辑
+     */
+    void onClockAlertChanged(long date, boolean set);
+
+    /**
+     * 当用户通过小部件创建笔记时，该方法会被调用。
+     */
+    void onWidgetChanged();
+
+    /**
+     * 当笔记在清单模式（例如从普通模式切换到勾选清单模式或者反过来切换）发生改变时，该方法会被调用。
+     * @param oldMode 传入的int类型参数，表示改变之前的模式值，可用于对比前后模式差异并进行相应的逻辑调整。
+     * @param newMode 传入的int类型参数，表示改变之后的新的模式值，方便根据新模式进行界面展示等相关逻辑的更新操作。
+     */
+    void onCheckListModeChanged(int oldMode, int newMode);
+}