diff --git a/doc/开源软件泛读、标注和维护报告文档.docx b/doc/开源软件泛读、标注和维护报告文档.docx index edd6488..f2910bf 100644 Binary files a/doc/开源软件泛读、标注和维护报告文档.docx and b/doc/开源软件泛读、标注和维护报告文档.docx differ diff --git a/src/Notes2/src/net/micode/notes/ui/NotesListActivity.java b/src/Notes2/src/net/micode/notes/ui/NotesListActivity.java index e843aec..66aedec 100644 --- a/src/Notes2/src/net/micode/notes/ui/NotesListActivity.java +++ b/src/Notes2/src/net/micode/notes/ui/NotesListActivity.java @@ -14,116 +14,150 @@ * limitations under the License. */ +/** + * 代表这个类是UI包中的一个 + */ package net.micode.notes.ui; -import android.app.Activity; -import android.app.AlertDialog; -import android.app.Dialog; -import android.appwidget.AppWidgetManager; -import android.content.AsyncQueryHandler; -import android.content.ContentResolver; -import android.content.ContentValues; -import android.content.Context; -import android.content.DialogInterface; -import android.content.Intent; -import android.content.SharedPreferences; -import android.database.Cursor; -import android.os.AsyncTask; -import android.os.Bundle; -import android.preference.PreferenceManager; -import android.text.Editable; -import android.text.TextUtils; -import android.text.TextWatcher; -import android.util.Log; -import android.view.ActionMode; -import android.view.ContextMenu; -import android.view.ContextMenu.ContextMenuInfo; -import android.view.Display; -import android.view.HapticFeedbackConstants; -import android.view.LayoutInflater; -import android.view.Menu; -import android.view.MenuItem; -import android.view.MenuItem.OnMenuItemClickListener; -import android.view.MotionEvent; -import android.view.View; -import android.view.View.OnClickListener; -import android.view.View.OnCreateContextMenuListener; -import android.view.View.OnTouchListener; -import android.view.inputmethod.InputMethodManager; -import android.widget.AdapterView; -import android.widget.AdapterView.OnItemClickListener; -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; - -import net.micode.notes.R; -import net.micode.notes.data.Notes; -import net.micode.notes.data.Notes.NoteColumns; -import net.micode.notes.gtask.remote.GTaskSyncService; -import net.micode.notes.model.WorkingNote; -import net.micode.notes.tool.BackupUtils; -import net.micode.notes.tool.DataUtils; -import net.micode.notes.tool.ResourceParser; -import net.micode.notes.ui.NotesListAdapter.AppWidgetAttribute; -import net.micode.notes.widget.NoteWidgetProvider_2x; -import net.micode.notes.widget.NoteWidgetProvider_4x; - -import java.io.BufferedReader; -import java.io.IOException; -import java.io.InputStream; -import java.io.InputStreamReader; -import java.util.HashSet; +/** + * 这些类涵盖了 Android 应用程序开发中常用的 + * UI 元素、数据存储、后台任务处理、系统服务调用等方面的功能。 + */ +import android.app.Activity; //表示应用程序中的一个活动，例如界面展示等 +import android.app.AlertDialog; //用于显示对话框的类 +import android.app.Dialog; //用于创建对话框的类 +import android.appwidget.AppWidgetManager; //用于管理桌面小组件的类 +import android.content.AsyncQueryHandler; //用于在后台执行异步数据库查询的处理器。 +import android.content.ContentResolver; //用于访问应用程序的内容提供者，进行数据的增删改查。 +import android.content.ContentValues; //用于存储键值对，用于对数据库进行操作。 +import android.content.Context; //表示 Android 应用程序的当前状态，提供访问应用程序的资源和类的接口。 +import android.content.DialogInterface; //用于创建对话框与用户进行交互。 +import android.content.Intent; //用于在应用程序内部或者不同应用程序之间进行交互或传递信息。 +import android.content.SharedPreferences; //用于存储应用程序的轻量级 key-value 数据。 +import android.database.Cursor; //用于在数据集中进行移动并访问查询结果。 +import android.os.AsyncTask; //用于在后台执行长时间运行的操作，并在主线程更新用户界面。 +import android.os.Bundle; //用于传递数据。 +import android.preference.PreferenceManager; //用于访问应用程序的默认共享偏好设置。 +import android.text.Editable; //表示文本框中的可编辑文本。 +import android.text.TextUtils; //用于处理和操作文本数据。 +import android.text.TextWatcher; //用于监听文本变化的接口。 +import android.util.Log; //用于在调试时记录日志。 +import android.view.ActionMode; //用于在用户界面上执行上下文操作的模式。 +import android.view.ContextMenu; //用于在视图组件上下文菜单的呈现。 +import android.view.ContextMenu.ContextMenuInfo; //提供有关创建上下文菜单的视图组件的额外信息。 +import android.view.Display; //表示屏幕上的显示内容。 +import android.view.HapticFeedbackConstants; //用于触觉反馈的常量值。 + + +import android.view.LayoutInflater; //用于动态加载 XML 布局文件。 +import android.view.Menu; //表示应用程序的菜单。 +import android.view.MenuItem; //用于表示菜单项。 +import android.view.MenuItem.OnMenuItemClickListener; //用于监听菜单项点击事件的接口。 +import android.view.MotionEvent; //用于表示单个事件的运动事件。 +import android.view.View; //用户界面上的可视元素。 +import android.view.View.OnClickListener; //用于监听视图点击事件的接口。 +import android.view.View.OnCreateContextMenuListener; //用于监听创建上下文菜单的接口。 +import android.view.View.OnTouchListener; //用于监听视图触摸事件的接口。 + + +import android.view.inputmethod.InputMethodManager; //用于管理输入法框架的接口。 +import android.widget.AdapterView; //用于在视图组件中表示数据项的子集合。 +import android.widget.AdapterView.OnItemClickListener; //用于监听列表项点击事件的接口。 +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; //用于显示简短消息的类。 +import net.micode.notes.R; //引用应用程序的资源。 +import net.micode.notes.data.Notes; //包含与笔记相关的数据的类。 + + +import net.micode.notes.data.Notes.NoteColumns; //包含笔记数据列的类。 +import net.micode.notes.gtask.remote.GTaskSyncService; //用于与 Google 任务同步服务进行交互的类 +import net.micode.notes.model.WorkingNote; //与正在编辑的笔记相关联的类。 +import net.micode.notes.tool.BackupUtils; //用于处理备份的工具类 +import net.micode.notes.tool.DataUtils; //包含处理数据的实用方法的类。 +import net.micode.notes.tool.ResourceParser; //用于解析资源的类。 +import net.micode.notes.ui.NotesListAdapter.AppWidgetAttribute; //用于在笔记列表适配器中表示应用程序小部件属性的类。 +import net.micode.notes.widget.NoteWidgetProvider_2x; //用于创建 2x 大小笔记应用程序小部件的类。 +import net.micode.notes.widget.NoteWidgetProvider_4x; //用于创建 4x 大小笔记应用程序小部件的类。用于创建 4x 大小笔记应用程序小部件的类。 + +import java.io.BufferedReader; //用于从字符输入流中读取文本的类。 +import java.io.IOException; //用于处理输入输出异常的类。 +import java.io.InputStream; //用于表示输入字节流的类。 +import java.io.InputStreamReader; //用于从字节流到字符流的桥梁。 +import java.util.HashSet; //用于表示一组不重复的元素的类。 + +/** + * 该类是Activity类的子类 + * 实现了监听用户点击的接口功能 + */ public class NotesListActivity extends Activity implements OnClickListener, OnItemLongClickListener { - private static final int FOLDER_NOTE_LIST_QUERY_TOKEN = 0; + /** + * 定义了一些静态常量 + */ + 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; //定义查询的相关变量 - private static final int MENU_FOLDER_DELETE = 0; + private static final int MENU_FOLDER_DELETE = 0; //标识用户是否选择了删除选项 - private static final int MENU_FOLDER_VIEW = 1; + private static final int MENU_FOLDER_VIEW = 1; //标识用户选择的外观 - private static final int MENU_FOLDER_CHANGE_NAME = 2; + private static final int MENU_FOLDER_CHANGE_NAME = 2; //标识用户是否选择重命名 private static final String PREFERENCE_ADD_INTRODUCTION = "net.micode.notes.introduction"; - + //定义一个字符串指向应用介绍 + + /** + * 这是一个枚举类型，用于表示列表的编辑状态。 + * 枚举类型可以用来定义一组相关的常量， + * 这里定义了三种可能的列表编辑状态： + * NOTE_LIST（便签列表）、SUB_FOLDER（子文件夹）、 + * CALL_RECORD_FOLDER（通话记录文件夹） + */ private enum ListEditState { NOTE_LIST, SUB_FOLDER, CALL_RECORD_FOLDER }; - private ListEditState mState; - - private BackgroundQueryHandler mBackgroundQueryHandler; + private ListEditState mState; //定义了一个标识列表编辑状态的变量 - private NotesListAdapter mNotesListAdapter; + private BackgroundQueryHandler mBackgroundQueryHandler; //用于在后台执行数据库查询等操作，以避免阻塞UI线程 - private ListView mNotesListView; + private NotesListAdapter mNotesListAdapter; //用于管理便签列表中数据项的适配器，通常与 ListView 一起使用 - private Button mAddNewNote; + private ListView mNotesListView; //它表示便签列表的视图，用于显示便签列表中的数据项， + // 并与适配器（NotesListAdapter）一起工作以展示数据。 - private boolean mDispatch; + /** + * 定义了一些类变量 + */ + private Button mAddNewNote; //声明了一个私有成员变量 mAddNewNote，类型为 Button， + // 用来表示一个按钮控件，通常用于用户点击以添加新的便签。 - private int mOriginY; + private boolean mDispatch; //声明了一个私有成员变量 mDispatch，类型为 boolean， + // 用来表示一个标志位，可能用于控制某些事件的分发。 - private int mDispatchY; + private int mOriginY; //声明了两个私有成员变量 mOriginY 和 mDispatchY，类型为 int， + private int mDispatchY; // 可能用于记录某些位置坐标的信息。 - private TextView mTitleBar; + private TextView mTitleBar; //声明了一个私有成员变量 mTitleBar，类型为 TextView， + // 用来表示一个文本视图，通常用于显示标题栏的文本信息。 - private long mCurrentFolderId; + private long mCurrentFolderId; //用来表示当前文件夹的ID。 - private ContentResolver mContentResolver; + private ContentResolver mContentResolver; //用来获取应用的内容提供者，用于访问应用的数据 - private ModeCallback mModeCallBack; + private ModeCallback mModeCallBack; //用于处理列表的编辑模式 - private static final String TAG = "NotesListActivity"; + private static final String TAG = "NotesListActivity"; //通常用于在日志或调试信息中标识类名 - public static final int NOTES_LISTVIEW_SCROLL_RATE = 30; + public static final int NOTES_LISTVIEW_SCROLL_RATE = 30; //表示便签列表视图的滚动速率 - private NoteItemData mFocusNoteDataItem; + private NoteItemData mFocusNoteDataItem; //用于表示当前焦点的便签数据项 private static final String NORMAL_SELECTION = NoteColumns.PARENT_ID + "=?"; @@ -131,9 +165,10 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt + 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; //分别表示启动Activity时用到的请求码，用于区分不同的启动请求 @Override protected void onCreate(Bundle savedInstanceState) { @@ -147,6 +182,17 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt setAppInfoFromRawRes(); } + /** + * 被重写的一个方法 + * 这是一个用于处理Activity返回结果的方法。 + * 当通过startActivityForResult方法启动的Activity结束后，会回调到这个方法。 + * 参数requestCode是用于标识请求的整型值， + * resultCode是用于标识返回结果的整型值， + * data是用于携带返回数据的Intent对象。 + * @param requestCode + * @param resultCode + * @param data + */ @Override protected void onActivityResult(int requestCode, int resultCode, Intent data) { if (resultCode == RESULT_OK @@ -157,6 +203,12 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt } } + /** + * 这是一个私有方法，用于从原始资源中获取应用信息并保存到SharedPreferences中。 + * 首先，它会检查SharedPreferences中是否已经添加了介绍信息， + * 如果没有，则读取raw资源中的介绍信息，并创建一个新的WorkingNote对象。 + * 接着，将介绍信息保存到SharedPreferences中，标记已经添加了介绍信息。 + */ private void setAppInfoFromRawRes() { SharedPreferences sp = PreferenceManager.getDefaultSharedPreferences(this); if (!sp.getBoolean(PREFERENCE_ADD_INTRODUCTION, false)) { @@ -203,12 +255,22 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt } } + /** + * 这是一个重写的Activity生命周期方法，当Activity即将可见时会调用此方法。 + * 在这个方法中，首先调用了父类的onStart方法，然后调用了startAsyncNotesListQuery方法。 + */ @Override protected void onStart() { super.onStart(); startAsyncNotesListQuery(); } + /** + * 这是一个私有方法，用于初始化资源。在这个方法中，对一些成员变量进行了初始化， + * 例如内容解析器、后台查询处理器、当前文件夹ID、便签列表视图、按钮的点击监听器等。 + * 这些初始化操作可以确保在Activity启动时，相关资源和状态都得到了正确的设置， + * 以便后续的操作和交互能够正常进行。 + */ private void initResources() { mContentResolver = this.getContentResolver(); mBackgroundQueryHandler = new BackgroundQueryHandler(this.getContentResolver()); @@ -231,11 +293,23 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt mModeCallBack = new ModeCallback(); } + /** + * 这个 ModeCallback 类实现了 + * ListView.MultiChoiceModeListener + * 和 OnMenuItemClickListener 接口， + * 用于处理列表的多选模式操作和菜单项点击事件的监听。 + */ private class ModeCallback implements ListView.MultiChoiceModeListener, OnMenuItemClickListener { private DropdownMenu mDropDownMenu; private ActionMode mActionMode; private MenuItem mMoveMenu; + /** + * 当进入多选模式时被调用，在这个方法中设置多选模式的界面和菜单。 + * @param mode + * @param menu + * @return + */ public boolean onCreateActionMode(ActionMode mode, Menu menu) { getMenuInflater().inflate(R.menu.note_list_options, menu); menu.findItem(R.id.delete).setOnMenuItemClickListener(this); @@ -269,6 +343,9 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt return true; } + /** + * 更新下拉菜单的显示状态，包括选中项的数量和标题等。 + */ private void updateMenu() { int selectedCount = mNotesListAdapter.getSelectedCount(); // Update dropdown menu @@ -286,11 +363,23 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt } } + /** + * 在准备多选模式时被调用，可以在这个方法中进行一些准备工作。 + * @param mode + * @param menu + * @return + */ public boolean onPrepareActionMode(ActionMode mode, Menu menu) { // TODO Auto-generated method stub return false; } + /** + * 在选择操作项时被调用，可以在这个方法中处理操作项的点击事件。 + * @param mode + * @param item + * @return + */ public boolean onActionItemClicked(ActionMode mode, MenuItem item) { // TODO Auto-generated method stub return false; @@ -319,28 +408,26 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt return true; } - 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); - builder.setMessage(getString(R.string.alert_message_delete_notes, - mNotesListAdapter.getSelectedCount())); - builder.setPositiveButton(android.R.string.ok, - new DialogInterface.OnClickListener() { - public void onClick(DialogInterface dialog, - int which) { - batchDelete(); - } - }); - builder.setNegativeButton(android.R.string.cancel, null); - builder.show(); - break; - case R.id.move: - startQueryDestinationFolders(); - break; - default: - return false; + int itemId = item.getItemId(); + if (itemId == 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); + builder.setMessage(getString(R.string.alert_message_delete_notes, + mNotesListAdapter.getSelectedCount())); + builder.setPositiveButton(android.R.string.ok, + new DialogInterface.OnClickListener() { + public void onClick(DialogInterface dialog, + int which) { + batchDelete(); + } + }); + builder.setNegativeButton(android.R.string.cancel, null); + builder.show(); + } else if (itemId == R.id.move) { + startQueryDestinationFolders(); + } else { + return false; } return true; } @@ -558,12 +645,8 @@ public class NotesListActivity extends Activity implements OnClickListener, OnIt } public void onClick(View v) { - switch (v.getId()) { - case R.id.btn_new_note: - createNewNote(); - break; - default: - break; + if (v.getId() == R.id.btn_new_note) { + createNewNote(); } } @@ -780,40 +863,27 @@ 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); - break; - } - case R.id.menu_export_text: { - exportNoteToText(); - break; - } - case R.id.menu_sync: { - if (isSyncMode()) { - if (TextUtils.equals(item.getTitle(), getString(R.string.menu_sync))) { - GTaskSyncService.startSync(this); - } else { - GTaskSyncService.cancelSync(this); - } + int itemId = item.getItemId(); + if (itemId == R.id.menu_new_folder) { + showCreateOrModifyFolderDialog(true); + } else if (itemId == R.id.menu_export_text) { + exportNoteToText(); + } else if (itemId == R.id.menu_sync) { + if (isSyncMode()) { + if (TextUtils.equals(item.getTitle(), getString(R.string.menu_sync))) { + GTaskSyncService.startSync(this); } else { - startPreferenceActivity(); + GTaskSyncService.cancelSync(this); } - break; - } - case R.id.menu_setting: { + } else { startPreferenceActivity(); - break; } - case R.id.menu_new_note: { - createNewNote(); - break; - } - case R.id.menu_search: - onSearchRequested(); - break; - default: - break; + } else if (itemId == R.id.menu_setting) { + startPreferenceActivity(); + } else if (itemId == R.id.menu_new_note) { + createNewNote(); + } else if (itemId == R.id.menu_search) { + onSearchRequested(); } return true; }