Time API Guide
PUBLISHED
Overview
The Tizen Time
API supports the use of locale-specific calendar features by enabling your application to retrieve the current local time for a given date. Time
API allows you to set a date and time for a particular time zone. It also facilitates converting one time zone to another. For a given date, you can perform calculations to convert local time to any date in the past, present, or future and also handle daylight saving time (DST) information. To use this API, add the required permissions to the config.xml
file (see prerequisites section below). When the application is launched, a time object is instantiated automatically in the tizen object. The tizen.time
object is an instance of the TimeUtil
interface, which provides date, time, and time zone management features.
Figure below shows how the API objects are structured inside the application window.
Time Object
Prerequisites
The Time
API has different levels of access to handle system and sensitive data. You can enable different permissions for the Time
API in the config.xml
file.
- http://tizen.org/api/time: Privilege to allow access to all features of the
Time
API - http://tizen.org/api/time.read: Privilege to allow access to the get current time, date, time zone, time and date formats
- http://tizen.org/api/time.write: Privilege to allow access to set the date and time
Get current date and time
The Time
API provides the TimeUtil
interface which allows you to work with current system date and current system time.
You can get and set the current system date and time.
-
Get Current Date and Time
The
TimeUtil.getCurrentDateTime
method retrieves the current system date and time. This method returns aTZDate
object.// Retrieves the current system date time and writes to console. var current_dt = tizen.time.getCurrentDateTime(); console.log ("current date / time is " + current_dt.toLocaleString());
In addition, you can use access functions like tizen.time.TZDate.getFullYear(), tizen.time.TZDate.getMonth(),.. to retrieve the information of individual fields year, month,etc .
Create and set new date and time
Create an instance of the Time
interface by passing the date, time and time zone values to the new tizen.TZDate()
method.
// Creates a time interface instance with the given values var newDT = new tizen.TZDate(2012, 9, 22, 2, 25, 23, 200, ); console.log ("date / time is " + newDT.toLocaleString());
-
Set Current Date and Time
You can use methods like
tizen.time.TZDate.setFullYear(), tizen.time.TZDate.setMonth(), tizen.time.TZDate.setHours(), tizen.time.TZDate.setMinutes()
.. to set the values for individual fields year, month, hours, minutes, etc .// Creates a time interface instance with the given values var newDT = new tizen.TZDate(2012, 9, 22, 2, 25, 23, 200, ); newDT.setMonth(2); // Sets month as March
The following table shows the parameter for the
TZDate
interface constructor.Parameter Format Example year YYYY (4-digit year) 2011 month MM (2-digit month) 11 day DD (2-digit day of month) 10 hours hh (2 digits of hours) 3 (or 03) minutes mm (2 digits of minutes) 45 seconds ss (2 digits of seconds) 4 (or 04) milliseconds (3 digits of milliseconds) 999 timezone specific descriptor 1/specific descriptor
2/specific descriptor n(string)America/Argentina/Buenos_Aires Other than the day parameter, which begins from 1, all parameters of theTZDate
constructor begin from 0. This implies that, for the months of a year, the value for January is 0, for February, it is 1, and for December, it is 11. Therefore it may be convenient to add 1 to the returned value oftizen.time.TZDate.getMonth()
method.
Get time zone information
-
Get Local time zone
The
TimeUtil.getLocalTimeZone
method is used to get the local time zone. This method returns time zone as a string.// Sets the system date and time to Sep 22, 2012 and 01:32:46 var newTZ = tizen.time.getLocalTimezone(); console.log ("Local time zone is " + newTZ);
-
Get available time zones
A list of available time zones can be obtained using the
tizen.time.getAvailableTimezones()
method.// Gets the list of available time zones and prints the number to console var tzList = tizen.time.getAvailableTimezones(); console.log ("The device supports " + tzList.length + "time zones");
-
Get time zone abbreviation
The
TZDate.getTimezoneAbbreviation()
method determines the time zone abbreviation to be used at a particular date in the time zone.// Gets abbrevation of the time zone var current_dt = tizen.time.getCurrentDateTime(); var tzAbbr = current_dt.getTimezoneAbbreviation(); console.log ("Time zone abbrevation " + tzAbbr);
Check date and time formats
The TimeUtil
interface provides methods for getting the format of the date and time.
-
Get Time Format
You can get the system's local time format using the
tizen.time.getTimeFormat()
method. Returns a string. For example, you can get "h:m:s ap", where h denotes hours (0 to 23 or 1 to 12 if AM/PM display), m denotes minutes (0 to 59), s denotes seconds (0 to 59) and ap stands for AM/PM display format.// Gets the system's local time format and prints to console var timeFormat = tizen.time.getTimeFormat(); console.log ("System's local time format " + timeFormat);
Many time formats are supported in Tizen which include hh:mm:ss (for example, 16:08:27), and hh:mm:ss ap (for example, 04:08:27 PM) -
Get Date Format
You can get the system's local date format using the
tizen.time.getDateFormat()
method. Returns a string. For example, you can get string "d/m/y", where d stands for day, m stands for month and y denotes year.// Gets the system's local date format and prints to console var dateFormat = tizen.time.getDateFormat(); console.log ("System's local date format " + dateFormat);
Many date formats are supported in Tizen which include DD/MM/YYYY (for example, 23/10/1996), YYYY-DD-MM (for example, 1996-23-10), and hybrid formats (for example, Wednesday, October 23, 1996.)
Check for leap year
A leap year is a year containing one extra day in order to keep the calendar year synchronized with the astronomical or seasonal year. In each leap year, the month of February has 29 days instead of 28.
If you are creating a calendar-based application or accepting a birth date on an application form, you must validate user input for a leap year date value. For example, 29/02/2011 is invalid user input.
The TimeUtil.isLeapYear
method is used to check whether the given year is a leap year. This method takes the year input in the YYYY format.
en.time.getCurrentDateTime(); var is_leap = tizen.time.isLeapYear(current_dt.getFullYear()); if (is_leap) console.log("This year is a leap year.");
TZDate
object, you only need to call the isLeapYear
method to check for a leap year.Time conversion
The Time
API’s TimeDuration
interface provides methods to convert time to local or specified time zone and to UTC standard time.
var now = tizen.time.getCurrentDateTime(); var newtz = now.toTimezone(); var str = newtz.getTimezone(); console.log("Converted time zone " + str); newtz = date.toLocalTimezone(); str = newtz.getTimezone(); console.log("Local time zone " + str); var tzUTC = newtz.toUTC(); console.log("UTC standard time " + tzUTC.toLocaleString());
Calculate difference in time
The Time
API’s TimeDuration
interface provides the difference method to calculate the difference between two date or time events without having to bother about the difference in the event units. TimeDuration.difference
method accepts another TimeDuration
object and performs a (this object – parameter object)
operation, and returns a TimeDuration object.
// Compute event1.duration - event2.duration var diff = event1.duration.difference(event2.duration); if (diff.length > 0) console.log("Event1 is longer than Event2"); else if (diff.length = 0) console.log("Event1 is as long as Event2"); else console.log("Event1 is shorter than Event2");
TimeDuration
object is equivalent to the largest possible unit amongst the source parameter units while making sure that precision is not lost in the result. This implies that if, for example, when the comparison is made between "1 hour" and "20 minutes", the result of the difference are displayed as 40 minutes, not 0.67 hour. Although the hour unit is bigger than the minute unit, the result is more precise if presented in minutes.Check whether daylight saving time enabled
Daylight saving time, also known as Summer time is used to make better use of daylight
The TzDate.isDST
method is used to check if DST has been enabled for the current time zone
var current_dt = tizen.time.getCurrentDateTime(); var is_DST = current_dt.isDST; if (is_DST) console.log("Day light saving is enabled");
-
Get previous DST transition
Returns the date of the previous daylight saving time transition for the timezone.
var now = tizen.time.getCurrentDateTime(); var tzDT = now.getPreviousDSTTransition();
-
Get Next DST transition
Returns the date of the next daylight saving time transition for the timezone.
var now = tizen.time.getCurrentDateTime(); var tzDT = now.getNextDSTTransition();
Change time duration
You can use the tizen.time.TZDate.addDuration()
method to add the specified number of seconds to the current time or the specified number of days to the current date; the duration is of type TimeDuration
.
// a journey in time var now = tizen.time.getCurrentDateTime(); var newDT = now.addDuration(new tizen.TimeDuration(5, "DAYS"));
Compare time
There are three methods for convenient time comparison: tizen.time.TZDate.equalsTo(), tizen.time.TZDate.earlierThan()
and tizen.time.TZDate.laterThan()
. Each of them should be applied to a TZDateobject
and each of them returns a boolean value.
if(newDT.equalsTo(myGetCurrentDateTime.currentDT) == false) { // changed if(newDT.earlierThan(myGetCurrentDateTime.currentDT) == true ) { // earlier - time has stepped back! } if(newDT.laterThan(myGetCurrentDateTime.currentDT) == true ) { // later - time has elapsed. } } else { // the same time! }