diff options
Diffstat (limited to 'core/java/android/widget/TextClock.java')
| -rw-r--r-- | core/java/android/widget/TextClock.java | 482 |
1 files changed, 482 insertions, 0 deletions
diff --git a/core/java/android/widget/TextClock.java b/core/java/android/widget/TextClock.java new file mode 100644 index 0000000..4c46658 --- /dev/null +++ b/core/java/android/widget/TextClock.java @@ -0,0 +1,482 @@ +/* + * Copyright (C) 2012 The Android Open Source Project + * + * 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. + */ + +package android.widget; + +import android.content.BroadcastReceiver; +import android.content.ContentResolver; +import android.content.Context; +import android.content.Intent; +import android.content.IntentFilter; +import android.content.res.TypedArray; +import android.database.ContentObserver; +import android.net.Uri; +import android.os.Handler; +import android.os.SystemClock; +import android.provider.Settings; +import android.text.format.DateFormat; +import android.util.AttributeSet; + +import com.android.internal.R; + +import java.util.Calendar; +import java.util.TimeZone; + +import static android.view.ViewDebug.ExportedProperty; +import static android.widget.RemoteViews.*; + +/** + * <p><code>TextClock</code> can display the current date and/or time as + * a formatted string.</p> + * + * <p>This view honors the 24-hour format system setting. As such, it is + * possible and recommended to provide two different formatting patterns: + * one to display the date/time in 24-hour mode and one to display the + * date/time in 12-hour mode.</p> + * + * <p>It is possible to determine whether the system is currently in + * 24-hour mode by calling {@link #is24HourModeEnabled()}.</p> + * + * <p>The rules used by this widget to decide how to format the date and + * time are the following:</p> + * <ul> + * <li>In 24-hour mode: + * <ul> + * <li>Use the value returned by {@link #getFormat24Hour()} when non-null</li> + * <li>Otherwise, use the value returned by {@link #getFormat12Hour()} when non-null</li> + * <li>Otherwise, use {@link #DEFAULT_FORMAT_24_HOUR}</li> + * </ul> + * </li> + * <li>In 12-hour mode: + * <ul> + * <li>Use the value returned by {@link #getFormat12Hour()} when non-null</li> + * <li>Otherwise, use the value returned by {@link #getFormat24Hour()} when non-null</li> + * <li>Otherwise, use {@link #DEFAULT_FORMAT_12_HOUR}</li> + * </ul> + * </li> + * </ul> + * + * <p>The {@link CharSequence} instances used as formatting patterns when calling either + * {@link #setFormat24Hour(CharSequence)} or {@link #setFormat12Hour(CharSequence)} can + * contain styling information. To do so, use a {@link android.text.Spanned} object.</p> + * + * @attr ref android.R.styleable#TextClock_format12Hour + * @attr ref android.R.styleable#TextClock_format24Hour + * @attr ref android.R.styleable#TextClock_timeZone + */ +@RemoteView +public class TextClock extends TextView { + /** + * The default formatting pattern in 12-hour mode. This pattenr is used + * if {@link #setFormat12Hour(CharSequence)} is called with a null pattern + * or if no pattern was specified when creating an instance of this class. + * + * This default pattern shows only the time, hours and minutes, and an am/pm + * indicator. + * + * @see #setFormat12Hour(CharSequence) + * @see #getFormat12Hour() + */ + public static final CharSequence DEFAULT_FORMAT_12_HOUR = "h:mm aa"; + + /** + * The default formatting pattern in 24-hour mode. This pattenr is used + * if {@link #setFormat24Hour(CharSequence)} is called with a null pattern + * or if no pattern was specified when creating an instance of this class. + * + * This default pattern shows only the time, hours and minutes. + * + * @see #setFormat24Hour(CharSequence) + * @see #getFormat24Hour() + */ + public static final CharSequence DEFAULT_FORMAT_24_HOUR = "k:mm"; + + private CharSequence mFormat12 = DEFAULT_FORMAT_12_HOUR; + private CharSequence mFormat24 = DEFAULT_FORMAT_24_HOUR; + + @ExportedProperty + private CharSequence mFormat; + @ExportedProperty + private boolean mHasSeconds; + + private boolean mAttached; + + private Calendar mTime; + private String mTimeZone; + + private final ContentObserver mFormatChangeObserver = new ContentObserver(new Handler()) { + @Override + public void onChange(boolean selfChange) { + chooseFormat(); + onTimeChanged(); + } + + @Override + public void onChange(boolean selfChange, Uri uri) { + chooseFormat(); + onTimeChanged(); + } + }; + + private final BroadcastReceiver mIntentReceiver = new BroadcastReceiver() { + @Override + public void onReceive(Context context, Intent intent) { + if (mTimeZone == null) { + if (intent.getAction().equals(Intent.ACTION_TIMEZONE_CHANGED)) { + final String timeZone = intent.getStringExtra("time-zone"); + createTime(timeZone); + } + onTimeChanged(); + } + } + }; + + private final Runnable mTicker = new Runnable() { + public void run() { + onTimeChanged(); + + long now = SystemClock.uptimeMillis(); + long next = now + (1000 - now % 1000); + + getHandler().postAtTime(mTicker, next); + } + }; + + /** + * Creates a new clock using the default patterns + * {@link #DEFAULT_FORMAT_24_HOUR} and {@link #DEFAULT_FORMAT_12_HOUR} + * respectively for the 24-hour and 12-hour modes. + * + * @param context The Context the view is running in, through which it can + * access the current theme, resources, etc. + */ + @SuppressWarnings("UnusedDeclaration") + public TextClock(Context context) { + super(context); + init(); + } + + /** + * Creates a new clock inflated from XML. This object's properties are + * intialized from the attributes specified in XML. + * + * This constructor uses a default style of 0, so the only attribute values + * applied are those in the Context's Theme and the given AttributeSet. + * + * @param context The Context the view is running in, through which it can + * access the current theme, resources, etc. + * @param attrs The attributes of the XML tag that is inflating the view + */ + @SuppressWarnings("UnusedDeclaration") + public TextClock(Context context, AttributeSet attrs) { + this(context, attrs, 0); + } + + /** + * Creates a new clock inflated from XML. This object's properties are + * intialized from the attributes specified in XML. + * + * @param context The Context the view is running in, through which it can + * access the current theme, resources, etc. + * @param attrs The attributes of the XML tag that is inflating the view + * @param defStyle The default style to apply to this view. If 0, no style + * will be applied (beyond what is included in the theme). This may + * either be an attribute resource, whose value will be retrieved + * from the current theme, or an explicit style resource + */ + public TextClock(Context context, AttributeSet attrs, int defStyle) { + super(context, attrs, defStyle); + + TypedArray a = context.obtainStyledAttributes(attrs, R.styleable.TextClock, defStyle, 0); + try { + CharSequence format; + + format = a.getText(R.styleable.TextClock_format12Hour); + mFormat12 = format == null ? DEFAULT_FORMAT_12_HOUR : format; + + format = a.getText(R.styleable.TextClock_format24Hour); + mFormat24 = format == null ? DEFAULT_FORMAT_24_HOUR : format; + + mTimeZone = a.getString(R.styleable.TextClock_timeZone); + } finally { + a.recycle(); + } + + init(); + } + + private void init() { + createTime(mTimeZone); + // Wait until onAttachedToWindow() to handle the ticker + chooseFormat(false); + } + + private void createTime(String timeZone) { + if (timeZone != null) { + mTime = Calendar.getInstance(TimeZone.getTimeZone(timeZone)); + } else { + mTime = Calendar.getInstance(); + } + } + + /** + * Returns the formatting pattern used to display the date and/or time + * in 12-hour mode. The formatting pattern syntax is described in + * {@link DateFormat}. + * + * @return A {@link CharSequence} or null. + * + * @see #setFormat12Hour(CharSequence) + * @see #is24HourModeEnabled() + */ + @ExportedProperty + public CharSequence getFormat12Hour() { + return mFormat12; + } + + /** + * Specifies the formatting pattern used to display the date and/or time + * in 12-hour mode. The formatting pattern syntax is described in + * {@link DateFormat}. + * + * If this pattern is set to null, {@link #getFormat24Hour()} will be used + * even in 12-hour mode. If both 24-hour and 12-hour formatting patterns + * are set to null, {@link #DEFAULT_FORMAT_24_HOUR} and + * {@link #DEFAULT_FORMAT_12_HOUR} will be used instead. + * + * @param format A date/time formatting pattern as described in {@link DateFormat} + * + * @see #getFormat12Hour() + * @see #is24HourModeEnabled() + * @see #DEFAULT_FORMAT_12_HOUR + * @see DateFormat + * + * @attr ref android.R.styleable#TextClock_format12Hour + */ + public void setFormat12Hour(CharSequence format) { + mFormat12 = format; + + chooseFormat(); + onTimeChanged(); + } + + /** + * Returns the formatting pattern used to display the date and/or time + * in 24-hour mode. The formatting pattern syntax is described in + * {@link DateFormat}. + * + * @return A {@link CharSequence} or null. + * + * @see #setFormat24Hour(CharSequence) + * @see #is24HourModeEnabled() + */ + @ExportedProperty + public CharSequence getFormat24Hour() { + return mFormat24; + } + + /** + * Specifies the formatting pattern used to display the date and/or time + * in 24-hour mode. The formatting pattern syntax is described in + * {@link DateFormat}. + * + * If this pattern is set to null, {@link #getFormat12Hour()} will be used + * even in 24-hour mode. If both 24-hour and 12-hour formatting patterns + * are set to null, {@link #DEFAULT_FORMAT_24_HOUR} and + * {@link #DEFAULT_FORMAT_12_HOUR} will be used instead. + * + * @param format A date/time formatting pattern as described in {@link DateFormat} + * + * @see #getFormat24Hour() + * @see #is24HourModeEnabled() + * @see #DEFAULT_FORMAT_24_HOUR + * @see DateFormat + * + * @attr ref android.R.styleable#TextClock_format24Hour + */ + public void setFormat24Hour(CharSequence format) { + mFormat24 = format; + + chooseFormat(); + onTimeChanged(); + } + + /** + * Indicates whether the system is currently using the 24-hour mode. + * + * When the system is in 24-hour mode, this view will use the pattern + * returned by {@link #getFormat24Hour()}. In 12-hour mode, the pattern + * returned by {@link #getFormat12Hour()} is used instead. + * + * If either one of the formats is null, the other format is used. If + * both formats are null, the default values {@link #DEFAULT_FORMAT_12_HOUR} + * and {@link #DEFAULT_FORMAT_24_HOUR} are used instead. + * + * @return true if time should be displayed in 24-hour format, false if it + * should be displayed in 12-hour format. + * + * @see #setFormat12Hour(CharSequence) + * @see #getFormat12Hour() + * @see #setFormat24Hour(CharSequence) + * @see #getFormat24Hour() + */ + public boolean is24HourModeEnabled() { + return DateFormat.is24HourFormat(getContext()); + } + + /** + * Indicates which time zone is currently used by this view. + * + * @return The ID of the current time zone or null if the default time zone, + * as set by the user, must be used + * + * @see TimeZone + * @see java.util.TimeZone#getAvailableIDs() + * @see #setTimeZone(String) + */ + public String getTimeZone() { + return mTimeZone; + } + + /** + * Sets the specified time zone to use in this clock. When the time zone + * is set through this method, system time zone changes (when the user + * sets the time zone in settings for instance) will be ignored. + * + * @param timeZone The desired time zone's ID as specified in {@link TimeZone} + * or null to user the time zone specified by the user + * (system time zone) + * + * @see #getTimeZone() + * @see java.util.TimeZone#getAvailableIDs() + * @see TimeZone#getTimeZone(String) + * + * @attr ref android.R.styleable#TextClock_timeZone + */ + public void setTimeZone(String timeZone) { + mTimeZone = timeZone; + + createTime(timeZone); + onTimeChanged(); + } + + /** + * Selects either one of {@link #getFormat12Hour()} or {@link #getFormat24Hour()} + * depending on whether the user has selected 24-hour format. + * + * Calling this method does not schedule or unschedule the time ticker. + */ + private void chooseFormat() { + chooseFormat(true); + } + + /** + * Selects either one of {@link #getFormat12Hour()} or {@link #getFormat24Hour()} + * depending on whether the user has selected 24-hour format. + * + * @param handleTicker true if calling this method should schedule/unschedule the + * time ticker, false otherwise + */ + private void chooseFormat(boolean handleTicker) { + final boolean format24Requested = is24HourModeEnabled(); + + if (format24Requested) { + mFormat = abc(mFormat24, mFormat12, DEFAULT_FORMAT_24_HOUR); + } else { + mFormat = abc(mFormat12, mFormat24, DEFAULT_FORMAT_12_HOUR); + } + + boolean hadSeconds = mHasSeconds; + mHasSeconds = DateFormat.hasSeconds(mFormat); + + if (handleTicker) { + if (hadSeconds != mHasSeconds) { + if (hadSeconds) getHandler().removeCallbacks(mTicker); + else mTicker.run(); + } + } + } + + /** + * Returns a if not null, else return b if not null, else return c. + */ + private static CharSequence abc(CharSequence a, CharSequence b, CharSequence c) { + return a == null ? (b == null ? c : b) : a; + } + + @Override + protected void onAttachedToWindow() { + super.onAttachedToWindow(); + + if (!mAttached) { + mAttached = true; + + registerReceiver(); + registerObserver(); + + createTime(mTimeZone); + + if (mHasSeconds) { + mTicker.run(); + } else { + onTimeChanged(); + } + } + } + + @Override + protected void onDetachedFromWindow() { + super.onDetachedFromWindow(); + + if (mAttached) { + unregisterReceiver(); + unregisterObserver(); + + getHandler().removeCallbacks(mTicker); + + mAttached = false; + } + } + + private void registerReceiver() { + final IntentFilter filter = new IntentFilter(); + + filter.addAction(Intent.ACTION_TIME_TICK); + filter.addAction(Intent.ACTION_TIME_CHANGED); + filter.addAction(Intent.ACTION_TIMEZONE_CHANGED); + + getContext().registerReceiver(mIntentReceiver, filter, null, getHandler()); + } + + private void registerObserver() { + final ContentResolver resolver = getContext().getContentResolver(); + resolver.registerContentObserver(Settings.System.CONTENT_URI, true, mFormatChangeObserver); + } + + private void unregisterReceiver() { + getContext().unregisterReceiver(mIntentReceiver); + } + + private void unregisterObserver() { + final ContentResolver resolver = getContext().getContentResolver(); + resolver.unregisterContentObserver(mFormatChangeObserver); + } + + private void onTimeChanged() { + mTime.setTimeInMillis(System.currentTimeMillis()); + setText(DateFormat.format(mFormat, mTime)); + } +} |