添加代码注释

2 months ago · 9065ce20dd
parent 05a1a73226
commit 9065ce20dd
1 changed files with 270 additions and 128 deletions
--- a/src/Notes-master/app/src/main/java/net/micode/notes/ui/NotesListActivity.java
+++ b/src/Notes-master/app/src/main/java/net/micode/notes/ui/NotesListActivity.java
@ -1,17 +1,14 @@
 /*
- * Copyright (c) 2010-2011, The MiCode Open Source Community (www.micode.net)
+ * 版权声明：2010-2011年，MiCode开源社区(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
+ * 本代码基于Apache许可证2.0版本发布（"许可证"）；
+ * 您可以在遵守许可证的前提下使用本文件；
+ * 您可以从以下地址获取许可证副本：
 *
 *        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;
@ -56,7 +53,6 @@ import android.widget.AdapterView.OnItemLongClickListener;
 import android.widget.Button;
 import android.widget.EditText;
 import android.widget.ListView;
-import android.widget.PopupMenu;
 import android.widget.TextView;
 import android.widget.Toast;

@ -78,96 +74,99 @@ 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 FOLDER_LIST_QUERY_TOKEN = 1;
+    
+    // 上下文菜单选项ID
    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;
-
+    
+    // 首选项键：用于标记是否已添加应用介绍便签
    private static final String PREFERENCE_ADD_INTRODUCTION = "net.micode.notes.introduction";
-
+    
+    // 列表编辑状态枚举
    private enum ListEditState {
-        NOTE_LIST, SUB_FOLDER, CALL_RECORD_FOLDER
+        NOTE_LIST,      // 主便签列表状态
+        SUB_FOLDER,     // 子文件夹状态
+        CALL_RECORD_FOLDER // 通话记录文件夹状态
    };
-
-    private ListEditState mState;
-
-    private BackgroundQueryHandler mBackgroundQueryHandler;
-
-    private NotesListAdapter mNotesListAdapter;
-
-    private ListView mNotesListView;
-
-    private Button mAddNewNote;
-
-    private boolean mDispatch;
-
-    private int mOriginY;
-
-    private int mDispatchY;
-
-    private TextView mTitleBar;
-
-    private long mCurrentFolderId;
-
-    private ContentResolver mContentResolver;
-
-    private ModeCallback mModeCallBack;
-
-    private static final String TAG = "NotesListActivity";
-
-    public static final int NOTES_LISTVIEW_SCROLL_RATE = 30;
-
-    private NoteItemData mFocusNoteDataItem;
-
+    
+    // 成员变量定义
+    private ListEditState mState;                      // 当前列表状态
+    private BackgroundQueryHandler mBackgroundQueryHandler; // 异步查询处理器
+    private NotesListAdapter mNotesListAdapter;       // 便签列表适配器
+    private ListView mNotesListView;                   // 便签列表视图
+    private Button mAddNewNote;                        // 添加新便签按钮
+    private boolean mDispatch;                         // 触摸事件分发标记
+    private int mOriginY;                              // 触摸事件原始Y坐标
+    private int mDispatchY;                            // 触摸事件分发Y坐标
+    private TextView mTitleBar;                        // 标题栏文本
+    private long mCurrentFolderId;                     // 当前文件夹ID
+    private ContentResolver mContentResolver;          // 内容解析器
+    private ModeCallback mModeCallBack;                // 多选择模式回调
+    private static final String TAG = "NotesListActivity"; // 日志标签
+    public static final int NOTES_LISTVIEW_SCROLL_RATE = 30; // 列表滚动速率
+    private NoteItemData mFocusNoteDataItem;           // 聚焦的便签数据项
+    
+    // 数据库查询条件常量
    private static final String NORMAL_SELECTION = NoteColumns.PARENT_ID + "=?";
-
    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;
+    private final static int REQUEST_CODE_NEW_NODE = 103;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.note_list);
-        initResources();
-
+        initResources(); // 初始化资源
+        
        /**
-         * Insert an introduction when user firstly use this application
+         * 当用户首次使用应用时插入介绍便签
+         * 从raw资源文件读取介绍内容并保存为新便签
         */
        setAppInfoFromRawRes();
    }

    @Override
    protected void onActivityResult(int requestCode, int resultCode, Intent data) {
+        // 处理便签编辑活动返回结果
        if (resultCode == RESULT_OK
                && (requestCode == REQUEST_CODE_OPEN_NODE || requestCode == REQUEST_CODE_NEW_NODE)) {
-            mNotesListAdapter.changeCursor(null);
+            mNotesListAdapter.changeCursor(null); // 刷新列表数据
        } else {
            super.onActivityResult(requestCode, resultCode, data);
        }
    }

+    /**
+     * 从原始资源文件设置应用介绍信息
+     * 首次启动时创建一个包含介绍内容的便签
+     */
    private void setAppInfoFromRawRes() {
        SharedPreferences sp = PreferenceManager.getDefaultSharedPreferences(this);
        if (!sp.getBoolean(PREFERENCE_ADD_INTRODUCTION, false)) {
            StringBuilder sb = new StringBuilder();
            InputStream in = null;
            try {
-                 in = getResources().openRawResource(R.raw.introduction);
+                // 读取raw资源中的介绍文本
+                in = getResources().openRawResource(R.raw.introduction);
                if (in != null) {
                    InputStreamReader isr = new InputStreamReader(in);
                    BufferedReader br = new BufferedReader(isr);
-                    char [] buf = new char[1024];
+                    char[] buf = new char[1024];
                    int len = 0;
                    while ((len = br.read(buf)) > 0) {
                        sb.append(buf, 0, len);
@ -180,21 +179,22 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
                e.printStackTrace();
                return;
            } finally {
-                if(in != null) {
+                if (in != null) {
                    try {
                        in.close();
                    } catch (IOException e) {
-                        // TODO Auto-generated catch block
                        e.printStackTrace();
                    }
                }
            }

+            // 创建并保存介绍便签
            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");
@ -206,13 +206,19 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
    @Override
    protected void onStart() {
        super.onStart();
-        startAsyncNotesListQuery();
+        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);
@ -220,9 +226,13 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
        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());
+        
+        // 初始化其他状态变量
        mDispatch = false;
        mDispatchY = 0;
        mOriginY = 0;
@ -231,14 +241,23 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
        mModeCallBack = new ModeCallback();
    }

+    /**
+     * 多选择模式回调类
+     * 实现ListView.MultiChoiceModeListener接口处理批量操作
+     */
    private class ModeCallback implements ListView.MultiChoiceModeListener, OnMenuItemClickListener {
-        private DropdownMenu mDropDownMenu;
-        private ActionMode mActionMode;
-        private MenuItem mMoveMenu;
-
+        private DropdownMenu mDropDownMenu; // 下拉菜单
+        private ActionMode mActionMode;     // 操作模式
+        
+        /**
+         * 创建操作模式时调用
+         * 初始化操作模式菜单和自定义视图
+         */
        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) {
@ -247,33 +266,40 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
                mMoveMenu.setVisible(true);
                mMoveMenu.setOnMenuItemClickListener(this);
            }
+            
            mActionMode = mode;
-            mNotesListAdapter.setChoiceMode(true);
+            mNotesListAdapter.setChoiceMode(true); // 启用列表选择模式
            mNotesListView.setLongClickable(false);
-            mAddNewNote.setVisibility(View.GONE);
-
+            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(){
+            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);
            if (item != null) {
                if (mNotesListAdapter.isAllSelected()) {
@ -287,15 +313,17 @@ 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);
@ -306,12 +334,20 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
            mActionMode.finish();
        }

+        /**
+         * 项目选中状态改变时调用
+         * 更新选中状态和菜单显示
+         */
        public void onItemCheckedStateChanged(ActionMode mode, int position, long id,
                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),
@ -321,6 +357,7 @@ 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);
@ -330,14 +367,14 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
                                             new DialogInterface.OnClickListener() {
                                                 public void onClick(DialogInterface dialog,
                                                         int which) {
-                                                     batchDelete();
+                                                     batchDelete(); // 批量删除便签
                                                 }
                                             });
                    builder.setNegativeButton(android.R.string.cancel, null);
                    builder.show();
                    break;
                case R.id.move:
-                    startQueryDestinationFolders();
+                    startQueryDestinationFolders(); // 查询目标文件夹
                    break;
                default:
                    return false;
@ -346,31 +383,32 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
        }
    }

+    /**
+     * 新便签按钮触摸事件监听器
+     * 处理按钮透明区域的触摸事件分发
+     */
    private class NewNoteOnTouchListener implements OnTouchListener {

        public boolean onTouch(View v, MotionEvent event) {
            switch (event.getAction()) {
                case MotionEvent.ACTION_DOWN: {
+                    // 获取屏幕和按钮尺寸
                    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
-                     */
+                    
+                    // 调整标题栏高度
                    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（单位：像素）和按钮上边界定义。
                     */
                    if (event.getY() < (event.getX() * (-0.12) + 94)) {
                        View view = mNotesListView.getChildAt(mNotesListView.getChildCount() - 1
@ -387,6 +425,7 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
                    break;
                }
                case MotionEvent.ACTION_MOVE: {
+                    // 处理移动事件的分发
                    if (mDispatch) {
                        mDispatchY += (int) event.getY() - mOriginY;
                        event.setLocation(event.getX(), mDispatchY);
@ -395,6 +434,7 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
                    break;
                }
                default: {
+                    // 处理事件结束
                    if (mDispatch) {
                        event.setLocation(event.getX(), mDispatchY);
                        mDispatch = false;
@ -408,6 +448,10 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt

    };

+    /**
+     * 启动异步便签列表查询
+     * 根据当前文件夹ID构建查询条件
+     */
    private void startAsyncNotesListQuery() {
        String selection = (mCurrentFolderId == Notes.ID_ROOT_FOLDER) ? ROOT_FOLDER_SELECTION
                : NORMAL_SELECTION;
@ -417,6 +461,10 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
                }, NoteColumns.TYPE + " DESC," + NoteColumns.MODIFIED_DATE + " DESC");
    }

+    /**
+     * 异步查询处理器内部类
+     * 处理数据库查询结果回调
+     */
    private final class BackgroundQueryHandler extends AsyncQueryHandler {
        public BackgroundQueryHandler(ContentResolver contentResolver) {
            super(contentResolver);
@ -426,11 +474,11 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
        protected void onQueryComplete(int token, Object cookie, Cursor cursor) {
            switch (token) {
                case FOLDER_NOTE_LIST_QUERY_TOKEN:
-                    mNotesListAdapter.changeCursor(cursor);
+                    mNotesListAdapter.changeCursor(cursor); // 更新列表适配器数据
                    break;
                case FOLDER_LIST_QUERY_TOKEN:
                    if (cursor != null && cursor.getCount() > 0) {
-                        showFolderListMenu(cursor);
+                        showFolderListMenu(cursor); // 显示文件夹选择菜单
                    } else {
                        Log.e(TAG, "Query folder failed");
                    }
@ -441,6 +489,10 @@ 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);
@ -448,6 +500,7 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
        builder.setAdapter(adapter, new DialogInterface.OnClickListener() {

            public void onClick(DialogInterface dialog, int which) {
+                // 批量移动便签到目标文件夹
                DataUtils.batchMoveToFolder(mContentResolver,
                        mNotesListAdapter.getSelectedItemIds(), adapter.getItemId(which));
                Toast.makeText(
@ -456,12 +509,16 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
                                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);
@ -469,20 +526,24 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
        this.startActivityForResult(intent, REQUEST_CODE_NEW_NODE);
    }

+    /**
+     * 批量删除便签
+     * 在后台线程中执行删除操作并更新桌面小部件
+     */
    private void batchDelete() {
        new AsyncTask<Void, Void, HashSet<AppWidgetAttribute>>() {
            protected HashSet<AppWidgetAttribute> doInBackground(Void... unused) {
+                // 获取选中便签关联的桌面小部件
                HashSet<AppWidgetAttribute> 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");
@ -494,6 +555,7 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
            @Override
            protected void onPostExecute(HashSet<AppWidgetAttribute> widgets) {
                if (widgets != null) {
+                    // 更新受影响的桌面小部件
                    for (AppWidgetAttribute widget : widgets) {
                        if (widget.widgetId != AppWidgetManager.INVALID_APPWIDGET_ID
                                && widget.widgetType != Notes.TYPE_WIDGET_INVALIDE) {
@ -501,11 +563,15 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
                        }
                    }
                }
-                mModeCallBack.finishActionMode();
+                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);
@ -514,16 +580,18 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt

        HashSet<Long> ids = new HashSet<Long>();
        ids.add(folderId);
+        // 获取文件夹内便签关联的桌面小部件
        HashSet<AppWidgetAttribute> 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
                        && widget.widgetType != Notes.TYPE_WIDGET_INVALIDE) {
@ -533,6 +601,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 +612,23 @@ 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();
+        mCurrentFolderId = data.getId(); // 更新当前文件夹ID
+        startAsyncNotesListQuery(); // 重新查询当前文件夹下的便签
+        
+        // 根据文件夹类型更新界面状态
        if (data.getId() == Notes.ID_CALL_RECORD_FOLDER) {
            mState = ListEditState.CALL_RECORD_FOLDER;
            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,16 +637,21 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
        mTitleBar.setVisibility(View.VISIBLE);
    }

+    @Override
    public void onClick(View v) {
+        // 按钮点击事件处理
        switch (v.getId()) {
            case R.id.btn_new_note:
-                createNewNote();
+                createNewNote(); // 创建新便签
                break;
            default:
                break;
        }
    }

+    /**
+     * 显示软键盘
+     */
    private void showSoftInput() {
        InputMethodManager inputMethodManager = (InputMethodManager) getSystemService(Context.INPUT_METHOD_SERVICE);
        if (inputMethodManager != null) {
@ -574,16 +659,26 @@ 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 是否为创建新文件夹
+     */
    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());
@ -600,7 +695,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,14 +703,18 @@ 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());
                    return;
                }
+                
+                // 执行文件夹创建或修改操作
                if (!create) {
                    if (!TextUtils.isEmpty(name)) {
                        ContentValues values = new ContentValues();
@ -637,16 +736,12 @@ 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) {
@ -658,22 +753,23 @@ 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();
                mTitleBar.setVisibility(View.GONE);
                break;
            case CALL_RECORD_FOLDER:
+                // 从通话记录文件夹返回根目录
                mCurrentFolderId = Notes.ID_ROOT_FOLDER;
                mState = ListEditState.NOTE_LIST;
                mAddNewNote.setVisibility(View.VISIBLE);
@ -681,15 +777,21 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
                startAsyncNotesListQuery();
                break;
            case NOTE_LIST:
-                super.onBackPressed();
+                super.onBackPressed(); // 根目录直接退出活动
                break;
            default:
                break;
        }
    }

+    /**
+     * 更新桌面小部件
+     * @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) {
@ -703,10 +805,14 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
            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) {
@ -721,7 +827,7 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
    @Override
    public void onContextMenuClosed(Menu menu) {
        if (mNotesListView != null) {
-            mNotesListView.setOnCreateContextMenuListener(null);
+            mNotesListView.setOnCreateContextMenuListener(null); // 清除上下文菜单监听器
        }
        super.onContextMenuClosed(menu);
    }
@ -732,11 +838,13 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
            Log.e(TAG, "The long click data item is null");
            return false;
        }
+        // 处理文件夹上下文菜单项点击
        switch (item.getItemId()) {
            case MENU_FOLDER_VIEW:
-                openFolder(mFocusNoteDataItem);
+                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,14 +852,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);
+                showCreateOrModifyFolderDialog(false); // 显示修改文件夹名称对话框
                break;
            default:
                break;
@ -763,9 +871,10 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
    @Override
    public boolean onPrepareOptionsMenu(Menu menu) {
        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) {
@ -780,16 +889,18 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt

    @Override
    public boolean onOptionsItemSelected(MenuItem item) {
+        // 处理选项菜单点击事件
        switch (item.getItemId()) {
            case R.id.menu_new_folder: {
-                showCreateOrModifyFolderDialog(true);
+                showCreateOrModifyFolderDialog(true); // 显示创建文件夹对话框
                break;
            }
            case R.id.menu_export_text: {
-                exportNoteToText();
+                exportNoteToText(); // 导出便签为文本文件
                break;
            }
            case R.id.menu_sync: {
+                // 处理同步/取消同步操作
                if (isSyncMode()) {
                    if (TextUtils.equals(item.getTitle(), getString(R.string.menu_sync))) {
                        GTaskSyncService.startSync(this);
@ -797,20 +908,19 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
                        GTaskSyncService.cancelSync(this);
                    }
                } else {
-                    startPreferenceActivity();
+                    startPreferenceActivity(); // 启动设置活动
                }
                break;
-            }
            case R.id.menu_setting: {
-                startPreferenceActivity();
+                startPreferenceActivity(); // 启动设置活动
                break;
            }
            case R.id.menu_new_note: {
-                createNewNote();
+                createNewNote(); // 创建新便签
                break;
            }
            case R.id.menu_search:
-                onSearchRequested();
+                onSearchRequested(); // 启动搜索
                break;
            default:
                break;
@ -824,17 +934,22 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
        return true;
    }

+    /**
+     * 导出便签为文本文件
+     * 在后台线程中执行导出操作并显示结果
+     */
    private void exportNoteToText() {
        final BackupUtils backup = BackupUtils.getInstance(NotesListActivity.this);
        new AsyncTask<Void, Void, Integer>() {

            @Override
            protected Integer doInBackground(Void... unused) {
-                return backup.exportToText();
+                return backup.exportToText(); // 执行导出操作
            }

            @Override
            protected void onPostExecute(Integer result) {
+                // 根据导出结果显示不同的提示对话框
                if (result == BackupUtils.STATE_SD_CARD_UNMOUONTED) {
                    AlertDialog.Builder builder = new AlertDialog.Builder(NotesListActivity.this);
                    builder.setTitle(NotesListActivity.this
@ -866,21 +981,34 @@ 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 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();
@ -890,13 +1018,14 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
                    return;
                }

+                // 根据当前状态和项类型处理不同的点击操作
                switch (mState) {
                    case NOTE_LIST:
                        if (item.getType() == Notes.TYPE_FOLDER
                                || item.getType() == Notes.TYPE_SYSTEM) {
-                            openFolder(item);
+                            openFolder(item); // 打开文件夹
                        } else if (item.getType() == Notes.TYPE_NOTE) {
-                            openNode(item);
+                            openNode(item); // 打开便签
                        } else {
                            Log.e(TAG, "Wrong note type in NOTE_LIST");
                        }
@ -904,7 +1033,7 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
                    case SUB_FOLDER:
                    case CALL_RECORD_FOLDER:
                        if (item.getType() == Notes.TYPE_NOTE) {
-                            openNode(item);
+                            openNode(item); // 打开便签
                        } else {
                            Log.e(TAG, "Wrong note type in SUB_FOLDER");
                        }
@ -917,11 +1046,16 @@ 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 + ")";

+        // 查询可移动到的目标文件夹
        mBackgroundQueryHandler.startQuery(FOLDER_LIST_QUERY_TOKEN,
                null,
                Notes.CONTENT_NOTE_URI,
@ -935,10 +1069,17 @@ 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);
@ -946,9 +1087,10 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt
                    Log.e(TAG, "startActionMode fails");
                }
            } else if (mFocusNoteDataItem.getType() == Notes.TYPE_FOLDER) {
+                // 文件夹长按显示上下文菜单
                mNotesListView.setOnCreateContextMenuListener(mFolderOnCreateContextMenuListener);
            }
        }
        return false;
    }
-}
+}