ui/DateTimePickerDialog

java/net/micode/notes/ui/DateTimePickerDialog.java

@@ -29,59 +29,131 @@ import android.content.DialogInterface.OnClickListener;
 import android.text.format.DateFormat;
 import android.text.format.DateUtils;
 
+/**
+ * 一个封装了 DateTimePicker 的对话框类，用于选择日期和时间。
+ *
+ * 提供了一个弹出式对话框界面，用户可以在其中选择具体的日期和时间，
+ * 并通过回调将结果返回给调用者。
+ */
 public class DateTimePickerDialog extends AlertDialog implements OnClickListener {
 
+    // 当前选中的日期时间
     private Calendar mDate = Calendar.getInstance();
+
+    // 是否使用 24 小时制显示时间
     private boolean mIs24HourView;
+
+    // 时间设置完成后的回调接口
     private OnDateTimeSetListener mOnDateTimeSetListener;
+
+    // 自定义的时间选择控件
     private DateTimePicker mDateTimePicker;
 
+
+    /**
+     * 用户点击“确定”按钮后触发的监听器接口。
+     */
     public interface OnDateTimeSetListener {
         void OnDateTimeSet(AlertDialog dialog, long date);
     }
 
+    /**
+     * 构造函数：创建一个带有初始时间的日期时间选择对话框。
+     *
+     * @param context 上下文环境
+     * @param date 初始时间（毫秒）
+     */
     public DateTimePickerDialog(Context context, long date) {
         super(context);
+
+        // 创建一个 DateTimePicker 实例作为核心选择控件
         mDateTimePicker = new DateTimePicker(context);
+
+        // 设置该控件为对话框的内容视图
         setView(mDateTimePicker);
+
+        // 设置日期时间变化监听器，用于更新内部时间和标题
         mDateTimePicker.setOnDateTimeChangedListener(new OnDateTimeChangedListener() {
             public void onDateTimeChanged(DateTimePicker view, int year, int month,
                     int dayOfMonth, int hourOfDay, int minute) {
+                // 更新 Calendar 对象中的各个时间字段
                 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(mDate.getTimeInMillis());
             }
         });
+
+        // 设置初始时间
         mDate.setTimeInMillis(date);
+
+        // 秒数设为 0，避免出现不必要的误差
         mDate.set(Calendar.SECOND, 0);
+
+        // 将当前时间同步到 DateTimePicker 控件中
         mDateTimePicker.setCurrentDate(mDate.getTimeInMillis());
+
+        // 设置“确定”按钮并绑定点击事件
         setButton(context.getString(R.string.datetime_dialog_ok), this);
+
+        // 设置“取消”按钮，不绑定点击事件
         setButton2(context.getString(R.string.datetime_dialog_cancel), (OnClickListener)null);
+
+        // 根据系统设置决定是否启用 24 小时制
         set24HourView(DateFormat.is24HourFormat(this.getContext()));
+
+        // 初始化对话框标题
         updateTitle(mDate.getTimeInMillis());
     }
 
+    /**
+     * 设置是否使用 24 小时制显示时间。
+     *
+     * @param is24HourView true 表示使用 24 小时制
+     */
     public void set24HourView(boolean is24HourView) {
         mIs24HourView = is24HourView;
     }
 
+    /**
+     * 设置时间设置完成后的回调监听器。
+     *
+     * @param callBack 监听器对象
+     */
     public void setOnDateTimeSetListener(OnDateTimeSetListener callBack) {
         mOnDateTimeSetListener = callBack;
     }
 
+    /**
+     * 更新对话框标题，显示当前选择的时间。
+     *
+     * @param date 要显示的时间（毫秒）
+     */
     private void updateTitle(long date) {
         int flag =
             DateUtils.FORMAT_SHOW_YEAR |
             DateUtils.FORMAT_SHOW_DATE |
             DateUtils.FORMAT_SHOW_TIME;
+
+        // 根据是否为 24 小时制设置格式标志
         flag |= mIs24HourView ? DateUtils.FORMAT_24HOUR : DateUtils.FORMAT_24HOUR;
+
+        // 设置对话框标题为格式化后的时间字符串
         setTitle(DateUtils.formatDateTime(this.getContext(), date, flag));
     }
 
+    /**
+     * 对话框按钮点击事件处理。
+     *
+     * @param arg0 点击的对话框
+     * @param arg1 被点击的按钮标识符
+     */
     public void onClick(DialogInterface arg0, int arg1) {
+        // 如果设置了监听器，则调用回调方法传递最终时间
         if (mOnDateTimeSetListener != null) {
             mOnDateTimeSetListener.OnDateTimeSet(this, mDate.getTimeInMillis());
         }