2Q1/ui/NoteItemData.java

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

// 所在包名，表明该类属于net.micode.notes.ui包下，用于UI相关的功能逻辑（推测）
package net.micode.notes.ui;

import android.content.Context;
import android.database.Cursor;
import android.text.TextUtils;

// 导入与数据相关的类，可能用于操作笔记数据等功能
import net.micode.notes.data.Contact;
import net.micode.notes.data.Notes;
import net.micode.notes.data.Notes.NoteColumns;
import net.micode.notes.tool.DataUtils;

// NoteItemData类，可能用于封装笔记相关的数据项，方便在UI层进行展示和操作等
public class NoteItemData {
    // 定义一个字符串数组，用于指定从数据库查询笔记数据时要获取的列名，对应Notes表中的各个字段
    static final String [] PROJECTION = new String [] {
        NoteColumns.ID,
        NoteColumns.ALERTED_DATE,
        NoteColumns.BG_COLOR_ID,
        NoteColumns.CREATED_DATE,
        NoteColumns.HAS_ATTACHMENT,
        NoteColumns.MODIFIED_DATE,
        NoteColumns.NOTES_COUNT,
        NoteColumns.PARENT_ID,
        NoteColumns.SNIPPET,
        NoteColumns.TYPE,
        NoteColumns.WIDGET_ID,
        NoteColumns.WIDGET_TYPE,
    };

    // 以下是各个列在PROJECTION数组中的索引位置，方便后续从Cursor中获取对应的值
    private static final int ID_COLUMN                    = 0;
    private static final int ALERTED_DATE_COLUMN          = 1;
    private static final int BG_COLOR_ID_COLUMN           = 2;
    private static final int CREATED_DATE_COLUMN          = 3;
    private static final int HAS_ATTACHMENT_COLUMN        = 4;
    private static final int MODIFIED_DATE_COLUMN         = 5;
    private static final int NOTES_COUNT_COLUMN           = 6;
    private static final int PARENT_ID_COLUMN             = 7;
    private static final int SNIPPET_COLUMN               = 8;
    private static final int TYPE_COLUMN                  = 9;
    private static final int WIDGET_ID_COLUMN             = 10;
    private static final int WIDGET_TYPE_COLUMN           = 11;

    // 笔记的唯一标识ID
    private long mId;
    // 提醒日期（可能是设置了提醒功能的笔记对应的提醒时间戳之类的）
    private long mAlertDate;
    // 背景颜色的ID，用于设置笔记展示的背景颜色（推测）
    private int mBgColorId;
    // 笔记创建日期的时间戳
    private long mCreatedDate;
    // 表示笔记是否有附件，true表示有附件，false表示没有
    private boolean mHasAttachment;
    // 笔记最后修改日期的时间戳
    private long mModifiedDate;
    // 笔记相关的数量（具体含义需结合业务，可能是子笔记数量之类的）
    private int mNotesCount;
    // 父级ID，可能表示该笔记所属的文件夹等的ID
    private long mParentId;
    // 笔记的摘要内容，简短描述笔记的文字信息
    private String mSnippet;
    // 笔记的类型，可能有不同分类（如普通笔记、系统笔记等，具体要看Notes类中定义的类型常量）
    private int mType;
    // 部件（Widget）的ID，可能和在桌面展示相关的部件有关（如果有此功能的话）
    private int mWidgetId;
    // 部件（Widget）的类型，同样和桌面部件相关（推测）
    private int mWidgetType;
    // 联系人姓名（如果笔记和联系人相关，比如通话记录对应的笔记等情况）
    private String mName;
    // 电话号码（如果笔记和通话记录等相关）
    private String mPhoneNumber;

    // 以下几个布尔变量用于标记笔记在列表中的位置相关的状态
    private boolean mIsLastItem;
    private boolean mIsFirstItem;
    private boolean mIsOnlyOneItem;
    private boolean mIsOneNoteFollowingFolder;
    private boolean mIsMultiNotesFollowingFolder;

    // 构造函数，用于根据传入的Context和Cursor来初始化NoteItemData对象的各个属性
    public NoteItemData(Context context, Cursor cursor) {
        // 从Cursor中获取笔记的ID，并赋值给mId属性
        mId = cursor.getLong(ID_COLUMN);
        // 从Cursor中获取提醒日期，并赋值给mAlertDate属性
        mAlertDate = cursor.getLong(ALERTED_DATE_COLUMN);
        // 从Cursor中获取背景颜色ID，并赋值给mBgColorId属性
        mBgColorId = cursor.getInt(BG_COLOR_ID_COLUMN);
        // 从Cursor中获取创建日期，并赋值给mCreatedDate属性
        mCreatedDate = cursor.getLong(CREATED_DATE_COLUMN);
        // 根据从Cursor中获取的是否有附件的标识（整数），转换为布尔值赋值给mHasAttachment属性
        mHasAttachment = (cursor.getInt(HAS_ATTACHMENT_COLUMN) > 0)? true : false;
        // 从Cursor中获取修改日期，并赋值给mModifiedDate属性
        mModifiedDate = cursor.getLong(MODIFIED_DATE_COLUMN);
        // 从Cursor中获取笔记数量，并赋值给mNotesCount属性
        mNotesCount = cursor.getInt(NOTES_COUNT_COLUMN);
        // 从Cursor中获取父级ID，并赋值给mParentId属性
        mParentId = cursor.getLong(PARENT_ID_COLUMN);
        // 从Cursor中获取笔记摘要内容，并赋值给mSnippet属性，同时去除一些特定的标记（TAG_CHECKED和TAG_UNCHECKED，具体含义需看NoteEditActivity类中的定义）
        mSnippet = cursor.getString(SNIPPET_COLUMN);
        mSnippet = mSnippet.replace(NoteEditActivity.TAG_CHECKED, "").replace(
                NoteEditActivity.TAG_UNCHECKED, "");
        // 从Cursor中获取笔记类型，并赋值给mType属性
        mType = cursor.getInt(TYPE_COLUMN);
        // 从Cursor中获取部件ID，并赋值给mWidgetId属性
        mWidgetId = cursor.getInt(WIDGET_ID_COLUMN);
        // 从Cursor中获取部件类型，并赋值给mWidgetType属性
        mWidgetType = cursor.getInt(WIDGET_TYPE_COLUMN);

        // 初始化电话号码为空字符串
        mPhoneNumber = "";
        // 如果父级ID是通话记录文件夹的ID（Notes.ID_CALL_RECORD_FOLDER，具体值需看Notes类定义）
        if (mParentId == Notes.ID_CALL_RECORD_FOLDER) {
            // 通过DataUtils工具类，根据笔记ID从ContentResolver中获取电话号码，并赋值给mPhoneNumber属性
            mPhoneNumber = DataUtils.getCallNumberByNoteId(context.getContentResolver(), mId);
            // 如果获取到的电话号码不为空
            if (!TextUtils.isEmpty(mPhoneNumber)) {
                // 通过Contact类的静态方法，根据电话号码获取联系人姓名，并赋值给mName属性
                mName = Contact.getContact(context, mPhoneNumber);
                // 如果获取联系人姓名失败（返回null），则将电话号码作为姓名
                if (mName == null) {
                    mName = mPhoneNumber;
                }
            }
        }

        // 如果联系人姓名还是为null（可能前面获取过程出现问题等情况），则设置为空字符串
        if (mName == null) {
            mName = "";
        }
        // 调用checkPostion方法来检查该笔记在列表中的位置相关状态
        checkPostion(cursor);
    }

    // 私有方法，用于检查该笔记在列表中的位置相关状态，通过Cursor中的信息来判断
    private void checkPostion(Cursor cursor) {
        // 判断是否是列表中的最后一项，根据Cursor的isLast方法结果赋值给mIsLastItem属性
        mIsLastItem = cursor.isLast()? true : false;
        // 判断是否是列表中的第一项，根据Cursor的isFirst方法结果赋值给mIsFirstItem属性
        mIsFirstItem = cursor.isFirst()? true : false;
        // 判断是否列表中只有一项，通过比较Cursor中的记录数量是否为1来赋值给mIsOnlyOneItem属性
        mIsOnlyOneItem = (cursor.getCount() == 1);
        // 初始化是否有多条笔记跟随在文件夹后的标记为false
        mIsMultiNotesFollowingFolder = false;
        // 初始化是否有一条笔记跟随在文件夹后的标记为false
        mIsOneNoteFollowingFolder = false;

        // 如果笔记类型是普通笔记（Notes.TYPE_NOTE）并且不是列表中的第一项
        if (mType == Notes.TYPE_NOTE &&!mIsFirstItem) {
            // 获取当前Cursor的位置（索引）
            int position = cursor.getPosition();
            // 将Cursor移动到前一条记录（上一条数据）
            if (cursor.moveToPrevious()) {
                // 如果前一条记录的类型是文件夹类型（Notes.TYPE_FOLDER）或者系统类型（Notes.TYPE_SYSTEM）
                if (cursor.getInt(TYPE_COLUMN) == Notes.TYPE_FOLDER
                        || cursor.getInt(TYPE_COLUMN) == Notes.TYPE_SYSTEM) {
                    // 判断如果总记录数大于当前位置（索引）加1，说明有多条笔记跟随在文件夹后
                    if (cursor.getCount() > (position + 1)) {
                        mIsMultiNotesFollowingFolder = true;
                    } else {
                        // 否则说明只有一条笔记跟随在文件夹后
                        mIsOneNoteFollowingFolder = true;
                    }
                }
                // 将Cursor再移回原来的下一条记录位置（保证Cursor位置状态的正确，避免影响后续操作）
                if (!cursor.moveToNext()) {
                    // 如果无法移回，抛出异常，表示出现了不正常的Cursor移动情况
                    throw new IllegalStateException("cursor move to previous but can't move back");
                }
            }
        }
    }

    // 判断是否有一条笔记跟随在文件夹后，对外提供的访问方法
    public boolean isOneFollowingFolder() {
        return mIsOneNoteFollowingFolder;
    }

    // 判断是否有多条笔记跟随在文件夹后，对外提供的访问方法
    public boolean isMultiFollowingFolder() {
        return mIsMultiNotesFollowingFolder;
    }

    // 判断是否是列表中的最后一项，对外提供的访问方法
    public boolean isLast() {
        return mIsLastItem;
    }

    // 获取联系人姓名（如果有相关的联系人信息），对外提供的访问方法
    public String getCallName() {
        return mName;
    }

    // 判断是否是列表中的第一项，对外提供的访问方法
    public boolean isFirst() {
        return mIsFirstItem;
    }

    // 判断是否列表中只有一项，对外提供的访问方法
    public boolean isSingle() {
        return mIsOnlyOneItem;
    }

    // 获取笔记的唯一标识ID，对外提供的访问方法
    public long getId() {
        return mId;
    }

    // 获取提醒日期，对外提供的访问方法
    public long getAlertDate() {
        return mAlertDate;
    }

    // 获取创建日期，对外提供的访问方法
    public long getCreatedDate() {
        return mCreatedDate;
    }

    // 判断笔记是否有附件，对外提供的访问方法
    public boolean hasAttachment() {
        return mHasAttachment;
    }

    // 获取修改日期，对外提供的访问方法
    public long getModifiedDate() {
        return mModifiedDate;
    }

    // 获取背景颜色ID，对外提供的访问方法
    public int getBgColorId() {
        return mBgColorId;
    }

    // 获取父级ID，对外提供的访问方法
    public long getParentId() {
        return mParentId;
    }

    // 获取笔记数量，对外提供的访问方法
    public int getNotesCount() {
        return mNotesCount;
    }

    // 获取文件夹ID（这里返回的就是父级ID，可能是为了语义更明确表示是文件夹相关的ID），对外提供的访问方法
    public long getFolderId () {
        return mParentId;
    }

    // 获取笔记类型，对外提供的访问方法
    public int getType() {
        return mType;
    }

    // 获取部件类型，对外提供的访问方法
    public int getWidgetType() {
        return mWidgetType;
    }

    // 获取部件ID，对外提供的访问方法
    public int getWidgetId() {
        return mWidgetId;
    }

    // 获取笔记摘要内容，对外提供的访问方法
    public String getSnippet() {
        return mSnippet;
    }

    // 判断笔记是否有提醒设置（根据提醒日期是否大于0来判断），对外提供的访问方法
    public boolean hasAlert() {
        return (mAlertDate > 0);
    }

    // 判断是否是通话记录相关的笔记（根据父级ID是否是通话记录文件夹ID并且电话号码不为空来判断），对外提供的访问方法
    public boolean isCallRecord() {
        return (mParentId == Notes.ID_CALL_RECORD_FOLDER &&!TextUtils.isEmpty(mPhoneNumber));
    }

    // 静态方法，用于从Cursor中获取笔记类型，方便在其他地方直接调用获取类型信息
    public static int getNoteType(Cursor cursor) {
        return cursor.getInt(TYPE_COLUMN);
    }
}