xiaomi/ui/DateTimePickerDialog.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
package net.micode.notes.ui;

import java.util.Calendar;

import net.micode.notes.R;
import net.micode.notes.ui.DateTimePicker;
import net.micode.notes.ui.DateTimePicker.OnDateTimeChangedListener;

import android.app.AlertDialog;
import android.content.Context;
import android.content.DialogInterface;
import android.content.DialogInterface.OnClickListener;
import android.text.format.DateFormat;
import android.text.format.DateUtils;

// DateTimePickerDialog类继承自AlertDialog，同时实现了OnClickListener接口，它是一个自定义的对话框类，用于展示日期和时间选择的界面，并在用户操作后返回选择的日期时间结果，方便用户在应用中进行日期时间的设置操作。
public class DateTimePickerDialog extends AlertDialog implements OnClickListener {

    // Calendar对象，用于存储当前在对话框中显示和操作的日期时间信息，初始化为当前系统时间，后续会根据用户在日期时间选择器中的操作进行更新。
    private Calendar mDate = Calendar.getInstance();
    // 用于标记是否处于24小时制视图，决定了日期时间选择器以及对话框标题中时间显示的格式（12小时制或24小时制）。
    private boolean mIs24HourView;
    // 定义一个接口类型的变量，用于设置当用户在对话框中点击确定按钮并设置好日期时间后触发的回调监听器，外部类可实现该接口来处理用户选择的日期时间结果。
    private OnDateTimeSetListener mOnDateTimeSetListener;
    // 用于显示日期和时间选择界面的DateTimePicker实例，用户通过它来实际操作选择具体的年、月、日、时、分等信息。
    private DateTimePicker mDateTimePicker;

    // 定义一个接口，供外部类实现，当用户在对话框中完成日期时间设置并点击确定按钮后，会调用该接口中的方法，将对话框实例以及选择的日期时间（以毫秒为单位的时间戳）传递给外部类进行后续处理。
    public interface OnDateTimeSetListener {
        void OnDateTimeSet(AlertDialog dialog, long date);
    }

    // 构造函数，创建一个DateTimePickerDialog实例，传入上下文（Context）以及初始的日期时间（以毫秒为单位的时间戳）参数，用于初始化对话框的相关属性和显示内容。
    public DateTimePickerDialog(Context context, long date) {
        super(context);
        // 创建一个DateTimePicker实例，用于在对话框中展示日期时间选择的界面，它内部包含了各种选择器（如日期、小时、分钟等选择器）供用户操作。
        mDateTimePicker = new DateTimePicker(context);
        // 将创建的DateTimePicker视图设置为对话框的主要显示内容，使得对话框展示出日期时间选择的界面给用户。
        setView(mDateTimePicker);

        // 为DateTimePicker设置日期时间改变的监听器，当用户在DateTimePicker上操作改变了日期、时间等信息时，会触发该监听器的onDateTimeChanged方法。
        mDateTimePicker.setOnDateTimeChangedListener(new OnDateTimeChangedListener() {
            public void onDateTimeChanged(DateTimePicker view, int year, int month,
                    int dayOfMonth, int hourOfDay, int minute) {
                // 根据用户在DateTimePicker上选择的新日期时间信息，更新内部存储的Calendar对象（mDate）的年、月、日、时、分等字段，使其保持与用户选择一致。
                mDate.set(Calendar.YEAR, year);
                mDate.set(Calendar.MONTH, month);
                mDate.set(Calendar.DAY_OF_MONTH, dayOfMonth);
                mDate.set(Calendar.HOUR_OF_DAY, hourOfDay);
                mDate.set(Calendar.MINUTE, minute);
                // 调用updateTitle方法，根据更新后的日期时间信息来更新对话框的标题，使其显示当前选择的日期时间。
                updateTitle(mDate.getTimeInMillis());
            }
        });

        // 设置内部存储的Calendar对象（mDate）的时间为传入的初始日期时间，并将秒数设置为0，确保初始时间的准确性和一致性。
        mDate.setTimeInMillis(date);
        mDate.set(Calendar.SECOND, 0);

        // 将DateTimePicker的当前显示日期时间设置为与内部存储的Calendar对象（mDate）一致，保证初始界面显示的时间是传入的初始时间。
        mDateTimePicker.setCurrentDate(mDate.getTimeInMillis());

        // 设置对话框的“确定”按钮文本（从资源文件中获取对应的字符串）以及点击该按钮的监听器为当前类实例（因为实现了OnClickListener接口），当用户点击“确定”按钮时会触发onClick方法进行相应处理。
        setButton(context.getString(R.string.datetime_dialog_ok), this);

        // 设置对话框的“取消”按钮文本（从资源文件中获取对应的字符串）以及点击该按钮的监听器为null，意味着点击“取消”按钮时不做额外的特定操作（通常会关闭对话框）。
        setButton2(context.getString(R.string.datetime_dialog_cancel), (OnClickListener)null);

        // 根据系统当前的时间格式设置（是否为24小时制）来初始化对话框的时间显示格式，调用set24HourView方法进行设置，同时会影响DateTimePicker内部时间选择器的显示格式。
        set24HourView(DateFormat.is24HourFormat(this.getContext()));

        // 初次更新对话框的标题，使其显示初始的日期时间信息，调用updateTitle方法根据当前的日期时间来设置合适的标题内容。
        updateTitle(mDate.getTimeInMillis());
    }

    // 用于设置对话框是否采用24小时制视图的方法，通过传入的布尔值参数来更新内部的mIs24HourView标记，并相应地影响日期时间选择器以及对话框标题中时间显示的格式。
    public void set24HourView(boolean is24HourView) {
        mIs24HourView = is24HourView;
    }

    // 用于设置当用户在对话框中点击确定按钮后触发的回调监听器的方法，外部类可以通过传入实现了OnDateTimeSetListener接口的实例来处理用户选择的日期时间结果。
    public void setOnDateTimeSetListener(OnDateTimeSetListener callBack) {
        mOnDateTimeSetListener = callBack;
    }

    // 私有方法，用于更新对话框的标题内容，根据传入的日期时间（以毫秒为单位的时间戳）以及当前设置的时间显示格式（24小时制或12小时制）等信息，生成合适的标题字符串并设置给对话框。
    private void updateTitle(long date) {
        int flag =
            DateUtils.FORMAT_SHOW_YEAR |  // 设置显示年份的格式标志
            DateUtils.FORMAT_SHOW_DATE |  // 设置显示日期（月、日等）的格式标志
            DateUtils.FORMAT_SHOW_TIME;    // 设置显示时间（时、分等）的格式标志

        // 根据是否为24小时制视图，添加对应的时间格式标志，用于控制时间在标题中的显示格式（24小时制或12小时制）。
        flag |= mIs24HourView? DateUtils.FORMAT_24HOUR : DateUtils.FORMAT_12HOUR;

        // 使用DateUtils工具类的formatDateTime方法，根据传入的上下文、日期时间以及格式标志等信息，生成格式化后的日期时间字符串，并设置为对话框的标题内容。
        setTitle(DateUtils.formatDateTime(this.getContext(), date, flag));
    }

    // 实现OnClickListener接口的方法，当用户点击对话框中的按钮（如“确定”按钮）时会被调用，根据按钮的点击情况以及是否设置了OnDateTimeSetListener监听器，进行相应的操作，例如将用户选择的日期时间结果传递给外部监听器进行处理。
    public void onClick(DialogInterface arg0, int arg1) {
        if (mOnDateTimeSetListener!= null) {
            // 如果设置了OnDateTimeSetListener监听器，调用其OnDateTimeSet方法，将当前对话框实例以及用户选择的日期时间（通过内部存储的Calendar对象获取时间戳）传递给外部类进行后续处理。
            mOnDateTimeSetListener.OnDateTimeSet(this, mDate.getTimeInMillis());
        }
    }

}