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 

 

 

 

• Get current date and time
• Create and set new date and time
• Get time zone information
• Check date and time formats
• Check for leap year
• Time conversion
• Calculate difference in time
• Check whether daylight saving enabled
• Change time duration
• Compare time

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 a TZDate 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 the TZDate 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 of tizen.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.");

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");

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!
}