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 poss ible 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
int ACCESSIBILITY_LIVE_REGION_ASSERTIVE Live region mode specifying that accessibility services should interrupt ongoing speech to immediately announce changes to this view.
int ACCESSIBILITY_LIVE_REGION_NONE Live region mode specifying that accessibility services should not automatically announce changes to this view.
int ACCESSIBILITY_LIVE_REGION_POLITE Live region mode specifying that accessibility services should announce changes to this view.
int DRAWING_CACHE_QUALITY_AUTO

Enables automatic quality mode for the drawing cache.

int DRAWING_CACHE_QUALITY_HIGH

Enables high quality mode for the drawing cache.

int DRAWING_CACHE_QUALITY_LOW

Enables low quality mode for the drawing cache.

int FIND_VIEWS_WITH_CONTENT_DESCRIPTION Find find views that contain the specified content description.
int FIND_VIEWS_WITH_TEXT Find views that render the specified text.
int FOCUSABLES_ALL View flag indicating whether addFocusables(ArrayList, int, int) should add all focusable Views regardless if they are focusable in touch mode.
int FOCUSABLES_TOUCH_MODE View flag indicating whether addFocusables(ArrayList, int, int) should add only Views focusable in touch mode.
int FOCUS_BACKWARD Use with focusSearch(int).
int FOCUS_DOWN Use with focusSearch(int).
int FOCUS_FORWARD Use with focusSearch(int).
int FOCUS_LEFT Use with focusSearch(int).
int FOCUS_RIGHT Use with focusSearch(int).
int FOCUS_UP Use with focusSearch(int).
int GONE This view is invisible, and it doesn't take any space for layout purposes.
int HAPTIC_FEEDBACK_ENABLED View flag indicating whether this view should have haptic feedback enabled for events such as long presses.
int IMPORTANT_FOR_ACCESSIBILITY_AUTO Automatically determine whether a view is important for accessibility.
int IMPORTANT_FOR_ACCESSIBILITY_NO The view is not important for accessibility.
int IMPORTANT_FOR_ACCESSIBILITY_NO_HIDE_DESCENDANTS The view is not important for accessibility, nor are any of its descendant views.
int IMPORTANT_FOR_ACCESSIBILITY_YES The view is important for accessibility.
int INVISIBLE This view is invisible, but it still takes up space for layout purposes.
int KEEP_SCREEN_ON View flag indicating that the screen should remain on while the window containing this view is visible to the user.
int LAYER_TYPE_HARDWARE

Indicates that the view has a hardware layer.

int LAYER_TYPE_NONE Indicates that the view does not have a layer.
int LAYER_TYPE_SOFTWARE

Indicates that the view has a software layer.

int LAYOUT_DIRECTION_INHERIT Horizontal layout direction of this view is inherited from its parent.
int LAYOUT_DIRECTION_LOCALE Horizontal layout direction of this view is from deduced from the default language script for the locale.
int LAYOUT_DIRECTION_LTR Horizontal layout direction of this view is from Left to Right.
int LAYOUT_DIRECTION_RTL Horizontal layout direction of this view is from Right to Left.
int MEASURED_HEIGHT_STATE_SHIFT Bit shift of MEASURED_STATE_MASK to get to the height bits for functions that combine both width and height into a single int, such as getMeasuredState() and the childState argument of resolveSizeAndState(int, int, int).
int MEASURED_SIZE_MASK Bits of getMeasuredWidthAndState() and getMeasuredWidthAndState() that provide the actual measured size.
int MEASURED_STATE_MASK Bits of getMeasuredWidthAndState() and getMeasuredWidthAndState() that provide the additional state bits.
int MEASURED_STATE_TOO_SMALL Bit of getMeasuredWidthAndState() and getMeasuredWidthAndState() that indicates the measured size is smaller that the space the view would like to have.
int NO_ID Used to mark a View that has no ID.
int OVER_SCROLL_ALWAYS Always allow a user to over-scroll this view, provided it is a view that can scroll.
int OVER_SCROLL_IF_CONTENT_SCROLLS Allow a user to over-scroll this view only if the content is large enough to meaningfully scroll, provided it is a view that can scroll.
int OVER_SCROLL_NEVER Never allow a user to over-scroll this view.
int SCREEN_STATE_OFF Indicates that the screen has changed state and is now off.
int SCREEN_STATE_ON Indicates that the screen has changed state and is now on.
int SCROLLBARS_INSIDE_INSET The scrollbar style to display the scrollbars inside the padded area, increasing the padding of the view.
int SCROLLBARS_INSIDE_OVERLAY The scrollbar style to display the scrollbars inside the content area, without increasing the padding.
int SCROLLBARS_OUTSIDE_INSET The scrollbar style to display the scrollbars at the edge of the view, increasing the padding of the view.
int SCROLLBARS_OUTSIDE_OVERLAY The scrollbar style to display the scrollbars at the edge of the view, without increasing the padding.
int SCROLLBAR_POSITION_DEFAULT Position the scroll bar at the default position as determined by the system.
int SCROLLBAR_POSITION_LEFT Position the scroll bar along the left edge.
int SCROLLBAR_POSITION_RIGHT Position the scroll bar along the right edge.
int SOUND_EFFECTS_ENABLED View flag indicating whether this view should have sound effects enabled for events such as clicking and touching.
int STATUS_BAR_HIDDEN This constant was deprecated in API level 14. Use SYSTEM_UI_FLAG_LOW_PROFILE instead.
int STATUS_BAR_VISIBLE This constant was deprecated in API level 14. Use SYSTEM_UI_FLAG_VISIBLE instead.
int SYSTEM_UI_FLAG_FULLSCREEN Flag for setSystemUiVisibility(int): View has requested to go into the normal fullscreen mode so that its content can take over the screen while still allowing the user to interact with the application.
int SYSTEM_UI_FLAG_HIDE_NAVIGATION Flag for setSystemUiVisibility(int): View has requested that the system navigation be temporarily hidden.
int SYSTEM_UI_FLAG_IMMERSIVE Flag for setSystemUiVisibility(int): View would like to remain interactive when hiding the navigation bar with SYSTEM_UI_FLAG_HIDE_NAVIGATION.
int SYSTEM_UI_FLAG_IMMERSIVE_STICKY Flag for setSystemUiVisibility(int): View would like to remain interactive when hiding the status bar with SYSTEM_UI_FLAG_FULLSCREEN and/or hiding the navigation bar with SYSTEM_UI_FLAG_HIDE_NAVIGATION.
int SYSTEM_UI_FLAG_LAYOUT_FULLSCREEN Flag for setSystemUiVisibility(int): View would like its window to be layed out as if it has requested SYSTEM_UI_FLAG_FULLSCREEN, even if it currently hasn't.
int SYSTEM_UI_FLAG_LAYOUT_HIDE_NAVIGATION Flag for setSystemUiVisibility(int): View would like its window to be layed out as if it has requested SYSTEM_UI_FLAG_HIDE_NAVIGATION, even if it currently hasn't.
int SYSTEM_UI_FLAG_LAYOUT_STABLE Flag for setSystemUiVisibility(int): When using other layout flags, we would like a stable view of the content insets given to fitSystemWindows(Rect).
int SYSTEM_UI_FLAG_LOW_PROFILE Flag for setSystemUiVisibility(int): View has requested the system UI to enter an unobtrusive "low profile" mode.
int SYSTEM_UI_FLAG_VISIBLE Special constant for setSystemUiVisibility(int): View has requested the system UI (status bar) to be visible (the default).
int SYSTEM_UI_LAYOUT_FLAGS Flags that can impact the layout in relation to system UI.
int TEXT_ALIGNMENT_CENTER Center the paragraph, e.g.
int TEXT_ALIGNMENT_GRAVITY Default for the root view.
int TEXT_ALIGNMENT_INHERIT
int TEXT_ALIGNMENT_TEXT_END Align to the end of the paragraph, e.g.
int TEXT_ALIGNMENT_TEXT_START Align to the start of the paragraph, e.g.
int TEXT_ALIGNMENT_VIEW_END Align to the end of the view, which is ALIGN_RIGHT if the view’s resolved layoutDirection is LTR, and ALIGN_LEFT otherwise.
int TEXT_ALIGNMENT_VIEW_START Align to the start of the view, which is ALIGN_LEFT if the view’s resolved layoutDirection is LTR, and ALIGN_RIGHT otherwise.
int TEXT_DIRECTION_ANY_RTL Text direction is using "any-RTL" algorithm.
int TEXT_DIRECTION_FIRST_STRONG Text direction is using "first strong algorithm".
int TEXT_DIRECTION_INHERIT Text direction is inherited thru ViewGroup
int TEXT_DIRECTION_LOCALE Text direction is coming from the system Locale.
int TEXT_DIRECTION_LTR Text direction is forced to LTR.
int TEXT_DIRECTION_RTL Text direction is forced to RTL.
String VIEW_LOG_TAG The logging tag used by this class with android.util.Log.
int VISIBLE This view is visible.
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 defStyle)
Creates a new clock inflated from XML.
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 pat terns. 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 th eme, 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 defStyle)

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
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 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 leve l 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.