Added in API level 17

TextClock


open class TextClock : TextView
kotlin.Any
   ↳ android.view.View
   ↳ android.widget.TextView
   ↳ android.widget.TextClock

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(java.lang.CharSequence) or setFormat12Hour(java.lang.CharSequence) can contain styling information. To do so, use a android.text.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
android:format12Hour Specifies the formatting pattern used to show the time and/or date in 12-hour mode.
android:format24Hour Specifies the formatting pattern used to show the time and/or date in 24-hour mode.
android:timeZone Specifies the time zone to use.
Inherited XML attributes
Inherited constants
Public constructors
TextClock(context: Context!)

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

TextClock(context: Context!, attrs: AttributeSet!)

Creates a new clock inflated from XML.

TextClock(context: Context!, attrs: AttributeSet!, defStyleAttr: Int)

Creates a new clock inflated from XML.

TextClock(context: Context!, attrs: AttributeSet!, defStyleAttr: Int, defStyleRes: Int)

Public methods
open CharSequence!

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

open CharSequence!

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

open String!

Indicates which time zone is currently used by this view.

open Boolean

Indicates whether the system is currently using the 24-hour mode.

open Unit

open Unit

Update the displayed time if necessary and invalidate the view.

open Unit

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

open Unit

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

open Unit
setTimeZone(timeZone: String!)

Sets the specified time zone to use in this clock.

Protected methods
open Unit

open Unit

Inherited functions
Properties
static CharSequence!

The default formatting pattern in 12-hour mode.

static CharSequence!

The default formatting pattern in 24-hour mode.

Inherited properties

XML attributes

android:format12Hour

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

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

android:format24Hour

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

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

android:timeZone

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 java.util.TimeZone for more information about time zone ids.

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

Public constructors

TextClock

Added in API level 17
TextClock(context: Context!)

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

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

TextClock

Added in API level 17
TextClock(
    context: Context!,
    attrs: AttributeSet!)

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 Context!: The Context the view is running in, through which it can access the current theme, resources, etc.
attrs AttributeSet!: The attributes of the XML tag that is inflating the view

TextClock

Added in API level 17
TextClock(
    context: Context!,
    attrs: AttributeSet!,
    defStyleAttr: Int)

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

Parameters
context Context!: The Context the view is running in, through which it can access the current theme, resources, etc.
attrs AttributeSet!: The attributes of the XML tag that is inflating the view
defStyleAttr Int: 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.

TextClock

Added in API level 21
TextClock(
    context: Context!,
    attrs: AttributeSet!,
    defStyleAttr: Int,
    defStyleRes: Int)

Public methods

getFormat12Hour

Added in API level 17
open fun getFormat12Hour(): CharSequence!

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

Return
CharSequence! A CharSequence or null.

getFormat24Hour

Added in API level 17
open fun getFormat24Hour(): CharSequence!

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

Return
CharSequence! A CharSequence or null.

getTimeZone

Added in API level 17
open fun getTimeZone(): String!

Indicates which time zone is currently used by this view.

Return
String! The ID of the current time zone or null if the default time zone, as set by the user, must be used

is24HourModeEnabled

Added in API level 17
open fun is24HourModeEnabled(): Boolean

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.

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

onVisibilityAggregated

Added in API level 24
open fun onVisibilityAggregated(isVisible: Boolean): Unit
Parameters
isVisible Boolean: true if this view and all of its ancestors are VISIBLE and this view's window is also visible

refreshTime

Added in API level 30
open fun refreshTime(): Unit

Update the displayed time if necessary and invalidate the view.

setFormat12Hour

Added in API level 17
open fun setFormat12Hour(format: CharSequence!): Unit

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 DateFormat#getBestDateTimePattern(java.util.Locale, String). This method takes care of generating a format string adapted to the desired locale.

Parameters
format CharSequence!: A date/time formatting pattern as described in DateFormat

setFormat24Hour

Added in API level 17
open fun setFormat24Hour(format: CharSequence!): Unit

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 DateFormat#getBestDateTimePattern(java.util.Locale, String). This method takes care of generating a format string adapted to the desired locale.

Parameters
format CharSequence!: A date/time formatting pattern as described in DateFormat

setTimeZone

Added in API level 17
open fun setTimeZone(timeZone: String!): Unit

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.

Parameters
timeZone String!: 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

onAttachedToWindow

Added in API level 17
protected open fun onAttachedToWindow(): Unit

onDetachedFromWindow

Added in API level 17
protected open fun onDetachedFromWindow(): Unit

Properties

DEFAULT_FORMAT_12_HOUR

Added in API level 17
Deprecated in API level 18
static val DEFAULT_FORMAT_12_HOUR: CharSequence!

Deprecated: Let the system use locale-appropriate defaults instead.

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

DEFAULT_FORMAT_24_HOUR

Added in API level 17
Deprecated in API level 18
static val DEFAULT_FORMAT_24_HOUR: CharSequence!

Deprecated: Let the system use locale-appropriate defaults instead.

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