Update DateTimePicker.java

src/java/net/micode/notes/ui/DateTimePicker.java

@@ -1,41 +1,42 @@
 /*
- * Copyright (c) 2010-2011, The MiCode Open Source Community (www.micode.net)
+ * 版权所有 (c) 2010-2011, MiCode 开源社区 (www.micode.net)
  *
- * Licensed under the Apache License, Version 2.0 (the "License");
+ * 本文件授权使用 Apache License, Version 2.0（以下简称“许可证”）；
- * 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.
  */
 
- // 指定类所在的包名
+// 指定类所在的包名
 package net.micode.notes.ui;
 
-// 导入所需的Java和Android类
+// 导入所需的 Java 和 Android 类
 import java.text.DateFormatSymbols;
 import java.util.Calendar;
 
 import net.micode.notes.R;
 
-
 import android.content.Context;
 import android.text.format.DateFormat;
 import android.view.View;
 import android.widget.FrameLayout;
 import android.widget.NumberPicker;
-// 定义一个名为DateTimePicker的类，它继承自FrameLayout
 
+/**
+ * DateTimePicker 类用于选择日期和时间。
+ * 它继承自 FrameLayout，提供了一个日期和时间选择器的界面。
+ * 该类支持 24 小时制和 12 小时制（AM/PM）两种模式。
+ */
 public class DateTimePicker extends FrameLayout {
-	//FrameLayout是布局模板之一
+    // 默认启用状态
-	//所有的子元素全部在屏幕的右上方
     private static final boolean DEFAULT_ENABLE_STATE = true;
 
+    // 常量定义
     private static final int HOURS_IN_HALF_DAY = 12;
     private static final int HOURS_IN_ALL_DAY = 24;
     private static final int DAYS_IN_ALL_WEEK = 7;
@@ -49,27 +50,26 @@ public class DateTimePicker extends FrameLayout {
     private static final int MINUT_SPINNER_MAX_VAL = 59;
     private static final int AMPM_SPINNER_MIN_VAL = 0;
     private static final int AMPM_SPINNER_MAX_VAL = 1;
-    //初始化控件
+
+    // 初始化控件
     private final NumberPicker mDateSpinner;
     private final NumberPicker mHourSpinner;
     private final NumberPicker mMinuteSpinner;
     private final NumberPicker mAmPmSpinner;
-    //NumberPicker是数字选择器
+
-    //这里定义的四个变量全部是在设置闹钟时需要选择的变量（如日期、时、分、上午或者下午）
+    // NumberPicker 是数字选择器
+    // 这里定义的四个变量分别用于选择日期、小时、分钟和上午/下午
     private Calendar mDate;
-    //定义了Calendar类型的变量mDate，用于操作时间
     private String[] mDateDisplayValues = new String[DAYS_IN_ALL_WEEK];
 
     private boolean mIsAm;
- 
     private boolean mIs24HourView;
- 
     private boolean mIsEnabled = DEFAULT_ENABLE_STATE;
- 
     private boolean mInitialising;
 
     private OnDateTimeChangedListener mOnDateTimeChangedListener;
 
+    // 监听器定义
     private NumberPicker.OnValueChangeListener mOnDateChangedListener = new NumberPicker.OnValueChangeListener() {
         @Override
         public void onValueChange(NumberPicker picker, int oldVal, int newVal) {
@@ -77,49 +77,41 @@ public class DateTimePicker extends FrameLayout {
             updateDateControl();
             onDateTimeChanged();
         }
-    };//OnValueChangeListener，这是时间改变监听器，这里主要是对日期的监听
+    };
-    //将现在日期的值传递给mDate；updateDateControl是同步操作
 
     private NumberPicker.OnValueChangeListener mOnHourChangedListener = new NumberPicker.OnValueChangeListener() {
-        //这里是对 小时（Hour） 的监听
+        @Override
-    	@Override
         public void onValueChange(NumberPicker picker, int oldVal, int newVal) {
             boolean isDateChanged = false;
             Calendar cal = Calendar.getInstance();
-            //声明一个Calendar的变量cal，便于后续的操作
             if (!mIs24HourView) {
                 if (!mIsAm && oldVal == HOURS_IN_HALF_DAY - 1 && newVal == HOURS_IN_HALF_DAY) {
                     cal.setTimeInMillis(mDate.getTimeInMillis());
                     cal.add(Calendar.DAY_OF_YEAR, 1);
                     isDateChanged = true;
-                    //这里是对于12小时制时，晚上11点和12点交替时对日期的更改
                 } else if (mIsAm && oldVal == HOURS_IN_HALF_DAY && newVal == HOURS_IN_HALF_DAY - 1) {
                     cal.setTimeInMillis(mDate.getTimeInMillis());
                     cal.add(Calendar.DAY_OF_YEAR, -1);
                     isDateChanged = true;
                 }
-                //这里是对于12小时制时，凌晨11点和12点交替时对日期的更改
                 if (oldVal == HOURS_IN_HALF_DAY - 1 && newVal == HOURS_IN_HALF_DAY ||
                         oldVal == HOURS_IN_HALF_DAY && newVal == HOURS_IN_HALF_DAY - 1) {
                     mIsAm = !mIsAm;
                     updateAmPmControl();
-                }//这里是对于12小时制时，中午11点和12点交替时对AM和PM的更改
+                }
             } else {
                 if (oldVal == HOURS_IN_ALL_DAY - 1 && newVal == 0) {
                     cal.setTimeInMillis(mDate.getTimeInMillis());
                     cal.add(Calendar.DAY_OF_YEAR, 1);
                     isDateChanged = true;
-                    //这里是对于24小时制时，晚上11点和12点交替时对日期的更改
                 } else if (oldVal == 0 && newVal == HOURS_IN_ALL_DAY - 1) {
                     cal.setTimeInMillis(mDate.getTimeInMillis());
                     cal.add(Calendar.DAY_OF_YEAR, -1);
                     isDateChanged = true;
                 }
-            } //这里是对于12小时制时，凌晨11点和12点交替时对日期的更改
+            }
             int newHour = mHourSpinner.getValue() % HOURS_IN_HALF_DAY + (mIsAm ? 0 : HOURS_IN_HALF_DAY);
-            //通过数字选择器对newHour的赋值
             mDate.set(Calendar.HOUR_OF_DAY, newHour);
-            //通过set函数将新的Hour值传给mDate
             onDateTimeChanged();
             if (isDateChanged) {
                 setCurrentYear(cal.get(Calendar.YEAR));
@@ -131,19 +123,15 @@ public class DateTimePicker extends FrameLayout {
 
     private NumberPicker.OnValueChangeListener mOnMinuteChangedListener = new NumberPicker.OnValueChangeListener() {
         @Override
-        //这里是对 分钟（Minute）改变的监听
         public void onValueChange(NumberPicker picker, int oldVal, int newVal) {
             int minValue = mMinuteSpinner.getMinValue();
             int maxValue = mMinuteSpinner.getMaxValue();
             int offset = 0;
-            //设置offset，作为小时改变的一个记录数据
             if (oldVal == maxValue && newVal == minValue) {
                 offset += 1;
             } else if (oldVal == minValue && newVal == maxValue) {
                 offset -= 1;
             }
-            //如果原值为59，新值为0，则offset加1
-            //如果原值为0，新值为59，则offset减1
             if (offset != 0) {
                 mDate.add(Calendar.HOUR_OF_DAY, offset);
                 mHourSpinner.setValue(getCurrentHour());
@@ -163,8 +151,7 @@ public class DateTimePicker extends FrameLayout {
     };
 
     private NumberPicker.OnValueChangeListener mOnAmPmChangedListener = new NumberPicker.OnValueChangeListener() {
-        //对AM和PM的监听
+        @Override
-    	@Override
         public void onValueChange(NumberPicker picker, int oldVal, int newVal) {
             mIsAm = !mIsAm;
             if (mIsAm) {
@@ -177,29 +164,42 @@ public class DateTimePicker extends FrameLayout {
         }
     };
 
+    /**
+     * 日期时间改变的监听器接口。
+     */
     public interface OnDateTimeChangedListener {
-        void onDateTimeChanged(DateTimePicker view, int year, int month,
+        void onDateTimeChanged(DateTimePicker view, int year, int month, int dayOfMonth, int hourOfDay, int minute);
-                int dayOfMonth, int hourOfDay, int minute);
     }
 
+    /**
+     * 构造函数，初始化 DateTimePicker。
+     * @param context 应用上下文。
+     */
     public DateTimePicker(Context context) {
         this(context, System.currentTimeMillis());
-    }//通过对数据库的访问，获取当前的系统时间
+    }
 
+    /**
+     * 构造函数，初始化 DateTimePicker。
+     * @param context 应用上下文。
+     * @param date 初始日期时间（毫秒）。
+     */
     public DateTimePicker(Context context, long date) {
         this(context, date, DateFormat.is24HourFormat(context));
-    }//上面函数的得到的是一个天文数字（1970至今的秒数），需要DateFormat将其变得有意义
+    }
 
+    /**
+     * 构造函数，初始化 DateTimePicker。
+     * @param context 应用上下文。
+     * @param date 初始日期时间（毫秒）。
+     * @param is24HourView 是否为 24 小时制。
+     */
     public DateTimePicker(Context context, long date, boolean is24HourView) {
         super(context);
-        //获取系统时间
         mDate = Calendar.getInstance();
         mInitialising = true;
         mIsAm = getCurrentHourOfDay() >= HOURS_IN_HALF_DAY;
         inflate(context, R.layout.datetime_picker, this);
-        //如果当前Activity里用到别的layout，比如对话框layout
-        //还要设置这个layout上的其他组件的内容，就必须用inflate()方法先将对话框的layout找出来
-        //然后再用findViewById()找到它上面的其它组件
         mDateSpinner = (NumberPicker) findViewById(R.id.date);
         mDateSpinner.setMinValue(DATE_SPINNER_MIN_VAL);
         mDateSpinner.setMaxValue(DATE_SPINNER_MAX_VAL);
@@ -214,28 +214,33 @@ public class DateTimePicker extends FrameLayout {
         mMinuteSpinner.setOnValueChangedListener(mOnMinuteChangedListener);
 
         String[] stringsForAmPm = new DateFormatSymbols().getAmPmStrings();
-        mAmPmSpinner = (NumberPicker) findViewById(R.id.amPm);
+        mAmPmSpinner = (NumberPicker) findViewById
+        (R.id.amPm);
         mAmPmSpinner.setMinValue(AMPM_SPINNER_MIN_VAL);
         mAmPmSpinner.setMaxValue(AMPM_SPINNER_MAX_VAL);
         mAmPmSpinner.setDisplayedValues(stringsForAmPm);
         mAmPmSpinner.setOnValueChangedListener(mOnAmPmChangedListener);
 
-        // update controls to initial state
+        // 更新控件到初始状态
         updateDateControl();
         updateHourControl();
         updateAmPmControl();
 
         set24HourView(is24HourView);
 
-        // set to current time
+        // 设置当前时间
         setCurrentDate(date);
 
         setEnabled(isEnabled());
 
-        // set the content descriptions
+        // 设置内容描述
         mInitialising = false;
     }
 
+    /**
+     * 设置是否启用 DateTimePicker。
+     * @param enabled 是否启用。
+     */
     @Override
     public void setEnabled(boolean enabled) {
         if (mIsEnabled == enabled) {
@@ -248,67 +253,62 @@ public class DateTimePicker extends FrameLayout {
         mAmPmSpinner.setEnabled(enabled);
         mIsEnabled = enabled;
     }
-    //存在疑问！！！！！！！！！！！！！setEnabled的作用
+
-    //下面的代码通过原程序的注释已经比较清晰，另外可以通过函数名来判断
+    /**
-    //下面的各函数主要是对上面代码引用到的各函数功能的实现
+     * 检查 DateTimePicker 是否启用。
+     * @return true 表示启用，false 表示禁用。
+     */
     @Override
     public boolean isEnabled() {
         return mIsEnabled;
     }
 
     /**
-     * Get the current date in millis
+     * 获取当前日期时间（毫秒）。
-     *
+     * @return 当前日期时间（毫秒）。
-     * @return the current date in millis
      */
     public long getCurrentDateInTimeMillis() {
         return mDate.getTimeInMillis();
-    }//实现函数——得到当前的秒数
+    }
 
     /**
-     * Set the current date
+     * 设置当前日期时间。
-     *
+     * @param date 当前日期时间（毫秒）。
-     * @param date The current date in millis
      */
     public void setCurrentDate(long date) {
         Calendar cal = Calendar.getInstance();
         cal.setTimeInMillis(date);
         setCurrentDate(cal.get(Calendar.YEAR), cal.get(Calendar.MONTH), cal.get(Calendar.DAY_OF_MONTH),
                 cal.get(Calendar.HOUR_OF_DAY), cal.get(Calendar.MINUTE));
-    }//实现函数功能——设置当前的时间，参数是date
+    }
 
     /**
-     * Set the current date
+     * 设置当前日期时间。
-     *
+     * @param year 年份。
-     * @param year The current year
+     * @param month 月份（0-11）。
-     * @param month The current month
+     * @param dayOfMonth 日期。
-     * @param dayOfMonth The current dayOfMonth
+     * @param hourOfDay 小时（0-23）。
-     * @param hourOfDay The current hourOfDay
+     * @param minute 分钟。
-     * @param minute The current minute
      */
-    public void setCurrentDate(int year, int month,
+    public void setCurrentDate(int year, int month, int dayOfMonth, int hourOfDay, int minute) {
-            int dayOfMonth, int hourOfDay, int minute) {
         setCurrentYear(year);
         setCurrentMonth(month);
         setCurrentDay(dayOfMonth);
         setCurrentHour(hourOfDay);
         setCurrentMinute(minute);
-    }//实现函数功能——设置当前的时间，参数是各详细的变量
+    }
 
     /**
-     * Get current year
+     * 获取当前年份。
-     *
+     * @return 当前年份。
-     * @return The current year
      */
-    //下面是得到year、month、day等值
     public int getCurrentYear() {
         return mDate.get(Calendar.YEAR);
     }
 
     /**
-     * Set current year
+     * 设置当前年份。
-     *
+     * @param year 当前年份。
-     * @param year The current year
      */
     public void setCurrentYear(int year) {
         if (!mInitialising && year == getCurrentYear()) {
@@ -320,18 +320,16 @@ public class DateTimePicker extends FrameLayout {
     }
 
     /**
-     * Get current month in the year
+     * 获取当前月份（0-11）。
-     *
+     * @return 当前月份（0-11）。
-     * @return The current month in the year
      */
     public int getCurrentMonth() {
         return mDate.get(Calendar.MONTH);
     }
 
     /**
-     * Set current month in the year
+     * 设置当前月份（0-11）。
-     *
+     * @param month 当前月份（0-11）。
-     * @param month The month in the year
      */
     public void setCurrentMonth(int month) {
         if (!mInitialising && month == getCurrentMonth()) {
@@ -343,18 +341,16 @@ public class DateTimePicker extends FrameLayout {
     }
 
     /**
-     * Get current day of the month
+     * 获取当前日期。
-     *
+     * @return 当前日期。
-     * @return The day of the month
      */
     public int getCurrentDay() {
         return mDate.get(Calendar.DAY_OF_MONTH);
     }
 
     /**
-     * Set current day of the month
+     * 设置当前日期。
-     *
+     * @param dayOfMonth 当前日期。
-     * @param dayOfMonth The day of the month
      */
     public void setCurrentDay(int dayOfMonth) {
         if (!mInitialising && dayOfMonth == getCurrentDay()) {
@@ -366,15 +362,15 @@ public class DateTimePicker extends FrameLayout {
     }
 
     /**
-     * Get current hour in 24 hour mode, in the range (0~23)
+     * 获取当前小时（0-23）。
-     * @return The current hour in 24 hour mode
+     * @return 当前小时（0-23）。
      */
     public int getCurrentHourOfDay() {
         return mDate.get(Calendar.HOUR_OF_DAY);
     }
 
     private int getCurrentHour() {
-        if (mIs24HourView){
+        if (mIs24HourView) {
             return getCurrentHourOfDay();
         } else {
             int hour = getCurrentHourOfDay();
@@ -387,9 +383,8 @@ public class DateTimePicker extends FrameLayout {
     }
 
     /**
-     * Set current hour in 24 hour mode, in the range (0~23)
+     * 设置当前小时（0-23）。
-     *
+     * @param hourOfDay 当前小时（0-23）。
-     * @param hourOfDay
      */
     public void setCurrentHour(int hourOfDay) {
         if (!mInitialising && hourOfDay == getCurrentHourOfDay()) {
@@ -415,16 +410,16 @@ public class DateTimePicker extends FrameLayout {
     }
 
     /**
-     * Get currentMinute
+     * 获取当前分钟。
-     *
+     * @return 当前分钟。
-     * @return The Current Minute
      */
     public int getCurrentMinute() {
         return mDate.get(Calendar.MINUTE);
     }
 
     /**
-     * Set current minute
+     * 设置当前分钟。
+     * @param minute 当前分钟。
      */
     public void setCurrentMinute(int minute) {
         if (!mInitialising && minute == getCurrentMinute()) {
@@ -436,16 +431,16 @@ public class DateTimePicker extends FrameLayout {
     }
 
     /**
-     * @return true if this is in 24 hour view else false.
+     * 检查是否为 24 小时制。
+     * @return true 表示 24 小时制，false 表示 12 小时制。
      */
-    public boolean is24HourView () {
+    public boolean is24HourView() {
         return mIs24HourView;
     }
 
     /**
-     * Set whether in 24 hour or AM/PM mode.
+     * 设置是否为 24 小时制。
-     *
+     * @param is24HourView true 表示 24 小时制，false 表示 12 小时制。
-     * @param is24HourView True for 24 hour mode. False for AM/PM mode.
      */
     public void set24HourView(boolean is24HourView) {
         if (mIs24HourView == is24HourView) {
@@ -471,7 +466,7 @@ public class DateTimePicker extends FrameLayout {
         mDateSpinner.setDisplayedValues(mDateDisplayValues);
         mDateSpinner.setValue(DAYS_IN_ALL_WEEK / 2);
         mDateSpinner.invalidate();
-    }// 对于星期几的算法
+    }
 
     private void updateAmPmControl() {
         if (mIs24HourView) {
@@ -480,7 +475,7 @@ public class DateTimePicker extends FrameLayout {
             int index = mIsAm ? Calendar.AM : Calendar.PM;
             mAmPmSpinner.setValue(index);
             mAmPmSpinner.setVisibility(View.VISIBLE);
-        }// 对于上下午操作的算法
+        }
     }
 
     private void updateHourControl() {
@@ -490,12 +485,12 @@ public class DateTimePicker extends FrameLayout {
         } else {
             mHourSpinner.setMinValue(HOUR_SPINNER_MIN_VAL_12_HOUR_VIEW);
             mHourSpinner.setMaxValue(HOUR_SPINNER_MAX_VAL_12_HOUR_VIEW);
-        }// 对与小时的算法
+        }
     }
 
     /**
-     * Set the callback that indicates the 'Set' button has been pressed.
+     * 设置日期时间改变的监听器。
-     * @param callback the callback, if null will do nothing
+     * @param callback 监听器，如果为 null 则不执行任何操作。
      */
     public void setOnDateTimeChangedListener(OnDateTimeChangedListener callback) {
         mOnDateTimeChangedListener = callback;
@@ -508,3 +503,4 @@ public class DateTimePicker extends FrameLayout {
         }
     }
 }
+```