/*
 * Copyright (c) 2010 - 2011, The MiCode Open Source Community (www.micode.net)
 * 版权声明部分，表明该代码遵循Apache License 2.0协议，同时说明了版权所属的开源社区以及相关许可的获取途径等信息。
 */

/*
 * 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.
 */

// 声明该类所属的包名，表明这个类位于net.micode.notes.ui包下，在项目的整体包结构中有其特定的组织和访问层级关系。
package net.micode.notes.ui;

// 导入必要的Android系统相关类，Context用于获取应用的上下文环境信息，是很多Android操作（如资源获取、系统服务调用等）的基础。
// Cursor用于处理数据库查询结果集，通过它可以遍历查询返回的数据记录等操作。
import android.content.Context;
import android.database.Cursor;
// 导入View和ViewGroup相关类，View是Android中所有可视化组件的基类，ViewGroup是可以包含其他子视图的视图容器类，用于构建复杂的UI布局结构。
import android.view.View;
import android.view.ViewGroup;
// 导入CursorAdapter类，这是Android中用于将数据库查询结果（Cursor）与ListView等列表视图进行适配的抽象类，子类需要实现特定方法来定制数据展示逻辑。
import android.widget.CursorAdapter;
// 导入LinearLayout类，用于创建线性布局，是一种常见的布局方式，可以按照水平或垂直方向排列子视图。
import android.widget.LinearLayout;
// 导入TextView类，用于在界面上展示文本信息，是显示文字内容的常用组件。
import android.widget.TextView;

// 导入项目中自动生成的资源类R，通过它可以访问项目中的各种资源（如布局文件、图片资源、字符串资源等），这里主要用于获取特定的字符串资源和布局文件资源。
// 同时导入了与数据相关的类Notes以及Notes类中的NoteColumns内部类，用于处理笔记数据相关的操作，比如获取数据列信息等。
import net.micode.notes.R;
import net.micode.notes.data.Notes;
import net.micode.notes.data.Notes.NoteColumns;

// FoldersListAdapter类继承自CursorAdapter抽象类，主要用于将数据库查询到的文件夹相关数据（以Cursor形式表示）适配到列表视图中进行展示，
// 并且提供了获取文件夹名称以及定制列表项视图显示内容等功能，方便在Android应用中展示文件夹列表信息。
public class FoldersListAdapter extends CursorAdapter {
    // 定义一个字符串数组常量PROJECTION，用于指定从数据库查询时需要获取的列信息，这里只包含了NoteColumns.ID（可能是文件夹的唯一标识符列）和NoteColumns.SNIPPET（可能是文件夹相关的简短描述等信息列）。
    public static final String [] PROJECTION = {
        NoteColumns.ID,
        NoteColumns.SNIPPET
    };

    // 定义一个常量ID_COLUMN，表示在PROJECTION数组中ID列的索引位置，这里初始化为0，方便后续通过索引快速获取对应列的数据。
    public static final int ID_COLUMN   = 0;
    // 定义一个常量NAME_COLUMN，表示在PROJECTION数组中用于显示名称的列（这里实际对应NoteColumns.SNIPPET列）的索引位置，初始化为1，用于后续按索引获取文件夹名称相关数据。
    public static final int NAME_COLUMN = 1;

    // FoldersListAdapter类的构造函数，用于创建该适配器的实例，接收一个Context类型的参数context用于获取应用的上下文环境信息，
    // 以及一个Cursor类型的参数c，这个Cursor包含了从数据库查询出来的文件夹相关数据，通过调用父类（CursorAdapter）的构造函数将这两个参数传递进去，完成父类的初始化以及基础的适配设置工作。
    public FoldersListAdapter(Context context, Cursor c) {
        super(context, c);
        // TODO Auto-generated constructor stub
        // 这里的TODO注释通常表示此处还有待完善或者补充的代码逻辑，可能后续需要根据具体业务需求进一步添加初始化相关的操作等内容。
    }

    // 重写CursorAdapter类中的newView方法，该方法用于创建一个新的视图（View）对象，用于在列表中展示每一项数据（在这里就是每个文件夹对应的列表项视图）。
    // 接收三个参数：Context类型的context用于获取应用的上下文环境信息，以便加载相关资源等；Cursor类型的cursor虽然在这里未使用，但在更复杂的场景下可以用于获取数据来初始化视图；
    // ViewGroup类型的parent表示该视图的父容器，用于确定视图的布局等相关属性。在这里返回一个新创建的FolderListItem对象，它是自定义的用于展示文件夹信息的列表项视图类。
    @Override
    public View newView(Context context, Cursor cursor, ViewGroup parent) {
        return new FolderListItem(context);
    }

    // 重写CursorAdapter类中的bindView方法，该方法用于将数据库查询到的数据（通过Cursor表示）绑定到已经创建好的视图（View）对象上，实现数据在视图上的展示。
    // 接收三个参数：View类型的view表示要绑定数据的视图对象，这里实际上就是前面newView方法创建的FolderListItem对象；Context类型的context用于获取应用的上下文环境信息；
    // Cursor类型的cursor包含了要绑定的数据记录。在方法内部，首先判断传入的视图是否是FolderListItem类型，如果是，则进行如下操作：
    // 获取文件夹的名称，通过判断当前记录中ID列的值是否等于Notes.ID_ROOT_FOLDER（可能是表示根文件夹的特定标识符）来决定显示的名称，
    // 如果是根文件夹，则获取R.string.menu_move_parent_folder对应的字符串资源作为名称（可能是显示“上级文件夹”之类的特定文本），否则获取NAME_COLUMN列对应的字符串作为文件夹名称。
    // 最后调用((FolderListItem) view).bind(folderName)方法，将获取到的文件夹名称传递给FolderListItem对象的bind方法，用于在对应的视图上（具体是TextView组件）显示文件夹名称。
    @Override
    public void bindView(View view, Context context, Cursor cursor) {
        if (view instanceof FolderListItem) {
            String folderName = (cursor.getLong(ID_COLUMN) == Notes.ID_ROOT_FOLDER)? context
                   .getString(R.string.menu_move_parent_folder) : cursor.getString(NAME_COLUMN);
            ((FolderListItem) view).bind(folderName);
        }
    }

    // 定义一个方法用于获取指定位置的文件夹名称，接收一个Context类型的参数context用于获取应用的上下文环境信息，以及一个int类型的参数position表示在列表中的位置索引。
    // 首先通过调用getItem方法（继承自CursorAdapter类）获取指定位置对应的Cursor对象（包含了该位置对应的文件夹数据记录），然后按照与bindView方法中类似的逻辑，
    // 判断该记录中ID列的值是否等于Notes.ID_ROOT_FOLDER，来决定返回的文件夹名称是特定的根文件夹名称字符串（从资源中获取）还是从NAME_COLUMN列获取的普通文件夹名称字符串，最终返回获取到的文件夹名称。
    public String getFolderName(Context context, int position) {
        Cursor cursor = (Cursor) getItem(position);
        return (cursor.getLong(ID_COLUMN) == Notes.ID_ROOT_FOLDER)? context
               .getString(R.string.menu_move_parent_folder) : cursor.getString(NAME_COLUMN);
    }

    // 定义一个内部私有类FolderListItem，它继承自LinearLayout，用于表示文件夹列表中的每一个列表项视图，内部包含了用于显示文件夹名称的TextView组件，
    // 并且提供了一个bind方法用于将文件夹名称数据绑定到TextView组件上进行显示，实现了列表项视图的数据展示逻辑定制。
    private class FolderListItem extends LinearLayout {
        // 定义一个TextView类型的成员变量mName，用于存储和显示文件夹的名称，是列表项视图中展示文本信息的核心组件。
        private TextView mName;

        // FolderListItem类的构造函数，用于创建该列表项视图的实例，接收一个Context类型的参数context用于获取应用的上下文环境信息，以便加载相关资源等。
        // 首先调用父类（LinearLayout）的构造函数，传入上下文环境context，完成父类的初始化操作，确保该列表项视图能继承LinearLayout的布局属性和功能。
        // 然后通过inflate方法加载名为R.layout.folder_list_item的布局文件，并将其填充到当前的FolderListItem实例中（也就是this所代表的当前对象），
        // 这个布局文件应该包含了用于展示文件夹信息的各个子控件（如这里的mName对应的TextView）的布局定义，使得这些控件能够在界面上显示出来。
        // 最后通过findViewById方法在已加载的布局中查找ID为R.id.tv_folder_name的视图控件，并将其转换为TextView类型赋值给mName成员变量，以便后续可以操作这个TextView来显示文件夹名称。
        public FolderListItem(Context context) {
            super(context);
            inflate(context, R.layout.folder_list_item, this);
            mName = (TextView) findViewById(R.id.tv_folder_name);
        }

        // 定义一个bind方法，用于将传入的文件夹名称数据绑定到TextView组件（mName）上进行显示，接收一个String类型的参数name表示要显示的文件夹名称，
        // 通过调用mName的setText方法，将传入的名称字符串设置为TextView的显示内容，从而实现在列表项视图上展示文件夹名称的功能。
        public void bind(String name) {
            mName.setText(name);
        }
    }

}