Android APIs
public class

TextClock

extends TextView
java.lang.Object
   ↳ android.view.View
     ↳ android.widget.TextView
       ↳ android.widget.TextClock

Class Overview

TextClock can display the current date and/or time as a formatted string.

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. Most callers will want to use the defaults, though, which will be appropriate for the user's locale.

It is possible to determine whether the system is currently in 24-hour mode by calling is24HourModeEnabled().

The rules used by this widget to decide how to format the date and time are the following:

  • In 24-hour mode:
    • Use the value returned by getFormat24Hour() when non-null
    • Otherwise, use the value returned by getFormat12Hour() when non-null
    • Otherwise, use a default value appropriate for the user's locale, such as h:mm a
  • In 12-hour mode:
    • Use the value returned by getFormat12Hour() when non-null
    • Otherwise, use the value returned by getFormat24Hour() when non-null
    • Otherwise, use a default value appropriate for the user's locale, such as HH:mm

The CharSequence instances used as formatting patterns when calling either setFormat24Hour(CharSequence) or setFormat12Hour(CharSequence) can contain styling information. To do so, use a Spanned object. Note that if you customize these strings, it is your responsibility to supply strings appropriate for formatting dates and/or times in the user's locale.

Summary

XML Attributes
Attribute Name Related Method Description
android:format12Hour setFormat12Hour(CharSequence) Specifies the formatting pattern used to show the time and/or date in 12-hour mode. 
android:format24Hour setFormat24Hour(CharSequence) Specifies the formatting pattern used to show the time and/or date in 24-hour mode. 
android:timeZone setTimeZone(String) Specifies the time zone to use. 
[Expand]
Inherited XML Attributes
From class android.widget.TextView
From class android.view.View
[Expand]
Inherited Constants
From class android.view.View
Fields
public static final CharSequence DEFAULT_FORMAT_12_HOUR This field was deprecated in API level 18. Let the system use locale-appropriate defaults instead.
public static final CharSequence DEFAULT_FORMAT_24_HOUR This field was deprecated in API level 18. Let the system use locale-appropriate defaults instead.
[Expand]
Inherited Fields
From class android.view.View
Public Constructors
TextClock(Context context)
Creates a new clock using the default patterns for the current locale.
TextClock(Context context, AttributeSet attrs)
Creates a new clock inflated from XML.
TextClock(Context context, AttributeSet attrs, int defStyleAttr)
Creates a new clock inflated from XML.
TextClock(Context context, AttributeSet attrs, int defStyleAttr, int defStyleRes)
Public Methods
CharSequence getFormat12Hour()
Returns the formatting pattern used to display the date and/or time in 12-hour mode.
CharSequence getFormat24Hour()
Returns the formatting pattern used to display the date and/or time in 24-hour mode.
String getTimeZone()
Indicates which time zone is currently used by this view.
boolean is24HourModeEnabled()
Indicates whether the system is currently using the 24-hour mode.
void setFormat12Hour(CharSequence format)

Specifies the formatting pattern used to display the date and/or time in 12-hour mode.

void setFormat24Hour(CharSequence format)

Specifies the formatting pattern used to display the date and/or time in 24-hour mode.

void setTimeZone(String timeZone)
Sets the specified time zone to use in this clock.
Protected Methods
void onAttachedToWindow()
This is called when the view is attached to a window.
void onDetachedFromWindow()
This is called when the view is detached from a window.
[Expand]
Inherited Methods
From class android.widget.TextView
From class android.view.View
From class java.lang.Object
From interface android.graphics.drawable.Drawable.Callback
From interface android.view.KeyEvent.Callback
From interface android.view.ViewTreeObserver.OnPreDrawListener
From interface android.view.accessibility.AccessibilityEventSource

XML Attributes

android:format12Hour

Specifies the formatting pattern used to show the time and/or date in 12-hour mode. Please refer to DateFormat for a complete description of accepted formatting patterns. The default pattern is a locale-appropriate equivalent of "h:mm a".

Must be a string value, using '\\;' to escape characters such as '\\n' or '\\uxxxx' for a unicode character.

This may also be a reference to a resource (in the form "@[package:]type:name") or theme attribute (in the form "?[package:][type:]name") containing a value of this type.

This corresponds to the global attribute resource symbol format12Hour.

android:format24Hour

Specifies the formatting pattern used to show the time and/or date in 24-hour mode. Please refer to DateFormat for a complete description of accepted formatting patterns. The default pattern is a locale-appropriate equivalent of "H:mm".

Must be a string value, using '\\;' to escape characters such as '\\n' or '\\uxxxx' for a unicode character.

This may also be a reference to a resource (in the form "@[package:]type:name") or theme attribute (in the form "?[package:][type:]name") containing a value of this type.

This corresponds to the global attribute resource symbol format24Hour.

android:timeZone

Specifies the time zone to use. When this attribute is specified, the TextClock will ignore the time zone of the system. To use the user's time zone, do not specify this attribute. The default value is the user's time zone. Please refer to TimeZone for more information about time zone ids.

Must be a string value, using '\\;' to escape characters such as '\\n' or '\\uxxxx' for a unicode character.

This may also be a reference to a resource (in the form "@[package:]type:name") or theme attribute (in the form "?[package:][type:]name") containing a value of this type.

This corresponds to the global attribute resource symbol timeZone.

Related Methods

Fields

public static final CharSequence DEFAULT_FORMAT_12_HOUR

Added in API level 17

This field was deprecated in API level 18.
Let the system use locale-appropriate defaults instead.

The default formatting pattern in 12-hour mode. This pattern is used if 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.

public static final CharSequence DEFAULT_FORMAT_24_HOUR

Added in API level 17

This field was deprecated in API level 18.
Let the system use locale-appropriate defaults instead.

The default formatting pattern in 24-hour mode. This pattern is used if 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.

Public Constructors

public TextClock (Context context)

Added in API level 17

Creates a new clock using the default patterns for the current locale.

Parameters
context The Context the view is running in, through which it can access the current theme, resources, etc.

public TextClock (Context context, AttributeSet attrs)

Added in API level 17

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.

Parameters
context The Context the view is running in, through which it can access the current theme, resources, etc.
attrs The attributes of the XML tag that is inflating the view

public TextClock (Context context, AttributeSet attrs, int defStyleAttr)

Added in API level 17

Creates a new clock inflated from XML. This object's properties are intialized from the attributes specified in XML.

Parameters
context The Context the view is running in, through which it can access the current theme, resources, etc.
attrs The attributes of the XML tag that is inflating the view
defStyleAttr An attribute in the current theme that contains a reference to a style resource that supplies default values for the view. Can be 0 to not look for defaults.

public TextClock (Context context, AttributeSet attrs, int defStyleAttr, int defStyleRes)

Public Methods

public CharSequence getFormat12Hour ()

Added in API level 17

Returns the formatting pattern used to display the date and/or time in 12-hour mode. The formatting pattern syntax is described in DateFormat.

Returns

public CharSequence getFormat24Hour ()

Added in API level 17

Returns the formatting pattern used to display the date and/or time in 24-hour mode. The formatting pattern syntax is described in DateFormat.

Returns

public String getTimeZone ()

Added in API level 17

Indicates which time zone is currently used by this view.

Returns
  • The ID of the current time zone or null if the default time zone, as set by the user, must be used

public boolean is24HourModeEnabled ()

Added in API level 17

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 getFormat24Hour(). In 12-hour mode, the pattern returned by getFormat12Hour() is used instead. If either one of the formats is null, the other format is used. If both formats are null, the default formats for the current locale are used.

Returns
  • true if time should be displayed in 24-hour format, false if it should be displayed in 12-hour format.

public void setFormat12Hour (CharSequence format)

Added in API level 17

Specifies the formatting pattern used to display the date and/or time in 12-hour mode. The formatting pattern syntax is described in DateFormat.

If this pattern is set to null, getFormat24Hour() will be used even in 12-hour mode. If both 24-hour and 12-hour formatting patterns are set to null, the default pattern for the current locale will be used instead.

Note: if styling is not needed, it is highly recommended you supply a format string generated by getBestDateTimePattern(java.util.Locale, String). This method takes care of generating a format string adapted to the desired locale.

Related XML Attributes
Parameters
format A date/time formatting pattern as described in DateFormat

public void setFormat24Hour (CharSequence format)

Added in API level 17

Specifies the formatting pattern used to display the date and/or time in 24-hour mode. The formatting pattern syntax is described in DateFormat.

If this pattern is set to null, getFormat24Hour() will be used even in 12-hour mode. If both 24-hour and 12-hour formatting patterns are set to null, the default pattern for the current locale will be used instead.

Note: if styling is not needed, it is highly recommended you supply a format string generated by getBestDateTimePattern(java.util.Locale, String). This method takes care of generating a format string adapted to the desired locale.

Related XML Attributes
Parameters
format A date/time formatting pattern as described in DateFormat

public void setTimeZone (String timeZone)

Added in API level 17

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.

Related XML Attributes
Parameters
timeZone The desired time zone's ID as specified in TimeZone or null to user the time zone specified by the user (system time zone)

Protected Methods

protected void onAttachedToWindow ()

Added in API level 17

This is called when the view is attached to a window. At this point it has a Surface and will start drawing. Note that this function is guaranteed to be called before onDraw(android.graphics.Canvas), however it may be called any time before the first onDraw -- including before or after onMeasure(int, int).

protected void onDetachedFromWindow ()

Added in API level 17

This is called when the view is detached from a window. At this point it no longer has a surface for drawing.