给WorkingNote.java添加代码注释

src/mi_note/app/src/main/java/net/micode/notes/model/WorkingNote.java

@@ -31,7 +31,12 @@ import net.micode.notes.data.Notes.NoteColumns;
 import net.micode.notes.data.Notes.TextNote;
 import net.micode.notes.tool.ResourceParser.NoteBgResources;
 
-
+/**
+ * @author hzx
+ * 版本：1.0
+ * 创建日期：2023/10/28
+ * 描述：WorkingNote  工作便签模型类，维护便签处于编辑模式时的状态
+ */
 public class WorkingNote {
     // Note for the working note
     private Note mNote;
@@ -42,26 +47,37 @@ public class WorkingNote {
     // Note mode
     private int mMode;
 
+    // 便签的提醒日期
     private long mAlertDate;
 
+    // 便签的上一次修改日期
     private long mModifiedDate;
 
+    // 便签的背景颜色
     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;
 
+    // 便签数据表字段的投影  即select后面的字段
     public static final String[] DATA_PROJECTION = new String[] {
             DataColumns.ID,
             DataColumns.CONTENT,
@@ -72,6 +88,7 @@ public class WorkingNote {
             DataColumns.DATA4,
     };
 
+    // 便签表字段的投影
     public static final String[] NOTE_PROJECTION = new String[] {
             NoteColumns.PARENT_ID,
             NoteColumns.ALERTED_DATE,
@@ -81,6 +98,9 @@ public class WorkingNote {
             NoteColumns.MODIFIED_DATE
     };
 
+    /**
+     * data表和note表中某些字段的索引
+     */
     private static final int DATA_ID_COLUMN = 0;
 
     private static final int DATA_CONTENT_COLUMN = 1;
@@ -101,12 +121,12 @@ public class WorkingNote {
 
     private static final int NOTE_MODIFIED_DATE_COLUMN = 5;
 
-    // New note construct
+    // 新便签的构造器  即当前编辑的便签是要新建的便签
     private WorkingNote(Context context, long folderId) {
         mContext = context;
         mAlertDate = 0;
         mModifiedDate = System.currentTimeMillis();
-        mFolderId = folderId;
+        mFolderId = folderId; // 设置所处文件夹的ID
         mNote = new Note();
         mNoteId = 0;
         mIsDeleted = false;
@@ -114,23 +134,28 @@ public class WorkingNote {
         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 != 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,40 +165,60 @@ public class WorkingNote {
             }
             cursor.close();
         } else {
+            // 查询结果为空
             Log.e(TAG, "No note with id:" + mNoteId);
+            // 抛出异常
             throw new IllegalArgumentException("Unable to find note with id " + mNoteId);
         }
+        // 加载便签的数据
         loadNoteData();
     }
 
+    /**
+     * 从数据库加载便签的数据并缓存
+     */
     private void loadNoteData() {
+        // 查询便签ID为mNoteId的便签数据
         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 {
+                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)) {
+                        // 提取便签电话号码数据ID
                         mNote.setCallDataId(cursor.getLong(DATA_ID_COLUMN));
                     } else {
+                        // 错误的数据类型
                         Log.d(TAG, "Wrong note type with type:" + type);
                     }
                 } while (cursor.moveToNext());
             }
             cursor.close();
-        } else {
+        } else { // 查询结果为空
             Log.e(TAG, "No data with id:" + mNoteId);
             throw new IllegalArgumentException("Unable to find note's data with id " + mNoteId);
         }
     }
 
+    /**
+     * 创建空的便签
+     * @param context 上下文
+     * @param folderId 所处文件夹ID
+     * @param widgetId 小组件ID
+     * @param widgetType 小组件类型
+     * @param defaultBgColorId 默认的背景颜色
+     * @return 工作便签
+     */
     public static WorkingNote createEmptyNote(Context context, long folderId, int widgetId,
             int widgetType, int defaultBgColorId) {
         WorkingNote note = new WorkingNote(context, folderId);
@@ -183,23 +228,38 @@ public class WorkingNote {
         return note;
     }
 
+    /**
+     * 通过便签ID来加载便签数据并创建一个工作便签
+     * @param context 上下文
+     * @param id 便签ID
+     * @return 工作便签
+     */
     public static WorkingNote load(Context context, long id) {
         return new WorkingNote(context, id, 0);
     }
 
+    /**
+     * 保存便签内容  线程安全  同步
+     * @return 是否保存成功
+     */
     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);
                     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
@@ -207,59 +267,99 @@ public class WorkingNote {
                 mNoteSettingStatusListener.onWidgetChanged();
             }
             return true;
-        } else {
+        } else { // 不应该保存
             return false;
         }
     }
 
+    /**
+     * 判断当前便签是否存在于数据库
+     * @return true or false
+     */
     public boolean existInDatabase() {
+        // 因为mNoteId的初始值为0，如果是从数据库中加载的正常便签，那mNoteId应该大于0
         return mNoteId > 0;
     }
 
+    /**
+     * 判断当前便签是否应该保存
+     * @return true or false
+     */
     private boolean isWorthSaving() {
         if (mIsDeleted || (!existInDatabase() && TextUtils.isEmpty(mContent))
                 || (existInDatabase() && !mNote.isLocalModified())) {
+            // 便签被删除 或 是新创建的便签但内容为空 或 数据库中已存在的便签但本地没有修改
+            // 不应该保存
             return false;
         } else {
+            // 应该保存
             return true;
         }
     }
 
+    /**
+     * 设置 便签设置状态改变监听器
+     * @param l 监听器
+     */
     public void setOnSettingStatusChangedListener(NoteSettingChangedListener l) {
         mNoteSettingStatusListener = l;
     }
 
+    /**
+     * 设置便签提醒日期
+     * @param date 日期
+     * @param set 是否设置提醒
+     */
     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) {
+            // 设置便签提醒监听
             mNoteSettingStatusListener.onClockAlertChanged(date, set);
         }
     }
 
+    /**
+     * 修改便签的删除标记
+     * @param mark 删除标记
+     */
     public void markDeleted(boolean mark) {
         mIsDeleted = mark;
         if (mWidgetId != AppWidgetManager.INVALID_APPWIDGET_ID
                 && mWidgetType != Notes.TYPE_WIDGET_INVALIDE && mNoteSettingStatusListener != null) {
+            // 更新小组件内容
             mNoteSettingStatusListener.onWidgetChanged();
         }
     }
 
+    /**
+     * 设置便签的背景颜色
+     * @param id 背景颜色ID
+     */
     public void setBgColorId(int id) {
-        if (id != mBgColorId) {
+        if (id != mBgColorId) { // 新的背景颜色
             mBgColorId = id;
             if (mNoteSettingStatusListener != null) {
+                // 改变便签背景颜色
                 mNoteSettingStatusListener.onBackgroundColorChanged();
             }
+            // 保存到数据库
             mNote.setNoteValue(NoteColumns.BG_COLOR_ID, String.valueOf(id));
         }
     }
 
+    /**
+     * 设置便签的查看模式  普通模式或者清单模式
+     * @param mode 模式标识
+     */
     public void setCheckListMode(int mode) {
-        if (mMode != mode) {
+        if (mMode != mode) { // 新的模式
             if (mNoteSettingStatusListener != null) {
+                // 实际改变便签的查看模式
                 mNoteSettingStatusListener.onCheckListModeChanged(mMode, mode);
             }
             mMode = mode;
@@ -267,99 +367,135 @@ public class WorkingNote {
         }
     }
 
+    /**
+     * 设置小组件的类型
+     * @param type 小组件类型标识
+     */
     public void setWidgetType(int type) {
-        if (type != mWidgetType) {
+        if (type != mWidgetType) { // 新的小组件类型
             mWidgetType = type;
             mNote.setNoteValue(NoteColumns.WIDGET_TYPE, String.valueOf(mWidgetType));
         }
     }
 
+    /**
+     * 设置小组件ID
+     * @param id 小组件ID
+     */
     public void setWidgetId(int id) {
-        if (id != mWidgetId) {
+        if (id != mWidgetId) { // 新的小组件ID
             mWidgetId = id;
             mNote.setNoteValue(NoteColumns.WIDGET_ID, String.valueOf(mWidgetId));
         }
     }
 
+    /**
+     * 设置工作便签的文本内容
+     * @param text 文本
+     */
     public void setWorkingText(String text) {
-        if (!TextUtils.equals(mContent, text)) {
+        if (!TextUtils.equals(mContent, text)) { // 文本发生变化
             mContent = text;
             mNote.setTextData(DataColumns.CONTENT, mContent);
         }
     }
 
+    /**
+     * 转换成通话记录便签
+     * @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));
     }
 
+    // 是否有闹钟提醒
     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
+         * 设置闹钟提醒时被调用
          */
         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
          */