intl/locale/nsIScriptableDateFormat.idl

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 #include "nsISupports.idl"
   7
   8 typedef long nsDateFormatSelector;
   9 %{ C++
  10 enum
  11 {
  12     kDateFormatNone = 0,            // do not include the date  in the format string
  13     kDateFormatLong,                // provides the long date format for the given locale
  14     kDateFormatShort,               // provides the short date format for the given locale
  15     kDateFormatYearMonth,           // formats using only the year and month
  16     kDateFormatWeekday              // week day (e.g. Mon, Tue)
  17 };
  18 %}
  19
  20 typedef long nsTimeFormatSelector;
  21 %{ C++
  22 enum
  23 {
  24     kTimeFormatNone = 0,            // don't include the time in the format string
  25     kTimeFormatSeconds,             // provides the time format with seconds in the  given locale
  26     kTimeFormatNoSeconds,           // provides the time format without seconds in the given locale
  27     kTimeFormatSecondsForce24Hour,  // forces the time format to use the 24 clock, regardless of the locale conventions
  28     kTimeFormatNoSecondsForce24Hour // forces the time format to use the 24 clock, regardless of the locale conventions
  29 };
  30 %}
  31
  32 %{C++
  33 // Define Contractid and CID
  34 // {2EA2E7D0-4095-11d3-9144-006008A6EDF6}
  35 #define NS_SCRIPTABLEDATEFORMAT_CID \
  36 { 0x2ea2e7d0, 0x4095, 0x11d3, { 0x91, 0x44, 0x0, 0x60, 0x8, 0xa6, 0xed, 0xf6 } }
  37
  38 #define NS_SCRIPTABLEDATEFORMAT_CONTRACTID "@mozilla.org/intl/scriptabledateformat;1"
  39
  40 extern nsresult
  41 NS_NewScriptableDateFormat(nsISupports* aOuter, REFNSIID aIID, void** aResult);
  42 %}
  43
  44 /**
  45  * Format date and time in a human readable format.
  46  */
  47 [scriptable, uuid(0c89efb0-1aae-11d3-9141-006008a6edf6)]
  48 interface nsIScriptableDateFormat : nsISupports
  49 {
  50     /**
  51      * Do not include the date in the format string.
  52      */
  53     const long dateFormatNone = 0;
  54
  55     /**
  56      * Provide the long date format.
  57      *
  58      * NOTE:
  59      * The original definitions of dateFormatLong and dateFormatShort are from
  60      * the Windows platform.
  61      * In US English dateFormatLong output will be like:
  62      *     Wednesday, January 29, 2003 4:02:14 PM
  63      * In US English dateFormatShort output will be like:
  64      *     1/29/03 4:02:14 PM
  65      * On platforms like Linux, it is rather difficult to achieve exact
  66      * same output, and since we are aiming at human readers, it does not make
  67      * sense to achieve exact same result. We will do just enough as the
  68      * platform allow us to do.
  69      */
  70     const long dateFormatLong = 1;
  71
  72     /**
  73      * Provide the short date format. See also dateFormatLong.
  74      */
  75     const long dateFormatShort = 2;
  76
  77     /**
  78      * Format using only the year and month.
  79      */
  80     const long dateFormatYearMonth = 3;
  81
  82     /**
  83      * Provide the Week day (e.g. Mo, Mon, Monday or similar).
  84      */
  85     const long dateFormatWeekday = 4;
  86
  87     /**
  88      * Don't include the time in the format string.
  89      */
  90     const long timeFormatNone = 0;
  91
  92     /**
  93      * Provide the time format with seconds.
  94      */
  95     const long timeFormatSeconds = 1;
  96
  97     /**
  98      * Provide the time format without seconds.
  99      */
 100     const long timeFormatNoSeconds = 2;
 101
 102     /**
 103      * Provide the time format with seconds, and force the time format to use
 104      * 24-hour clock, regardless of the locale conventions.
 105      */
 106     const long timeFormatSecondsForce24Hour = 3;
 107
 108     /**
 109      * Provide the time format without seconds, and force the time format to use
 110      * 24-hour clock, regardless of the locale conventions.
 111      */
 112     const long timeFormatNoSecondsForce24Hour = 4;
 113
 114     /**
 115      * Format the given date and time in a human readable format.
 116      *
 117      * The underlying operating system is used to format the date and time.
 118      *
 119      * Pass an empty string as the locale parameter to use the OS settings with
 120      * the preferred date and time formatting given by the user.
 121      *
 122      * Pass a locale code as described in nsILocale as the locale parameter
 123      * (e.g. en-US) to use a specific locale. If the given locale is not
 124      * available, a fallback will be used.
 125      *
 126      * NOTE: The output of this method depends on the operating system and user
 127      * settings. Even if you pass a locale code as the first parameter, there
 128      * are no guarantees about which locale and exact format the returned value
 129      * uses. Even if you know the locale, the format might be customized by the
 130      * user. Therefore you should not use the returned values in contexts where
 131      * you depend on any specific format or language.
 132      *
 133      * @param locale
 134      *        Locale code of locale used to format the date or an empty string
 135      *        to follow user preference.
 136      * @param dateFormatSelector
 137      *        Indicate which format should preferably be used for the date.
 138      *        Use one of the dateFormat* constants.
 139      * @param timeFormatSelector
 140      *        Indicate which format should preferably be used for the time.
 141      *        Use one of the timeFormat* constants.
 142      * @param year, month, day, hour, minute and second
 143      *        The date and time to be formatted, given in the computer's local
 144      *        time zone.
 145      * @return The date and time formatted as human readable text according to
 146      *         user preferences or the given locale.
 147      */
 148     wstring FormatDateTime(in wstring locale,
 149                            in long dateFormatSelector,
 150                            in long timeFormatSelector,
 151                            in long year,
 152                            in long month,
 153                            in long day,
 154                            in long hour,
 155                            in long minute,
 156                            in long second);
 157
 158     /**
 159      * Format the given date in a human readable format.
 160      *
 161      * See FormatDateTime for details.
 162      */
 163     wstring FormatDate(in wstring locale,
 164                        in long dateFormatSelector,
 165                        in long year,
 166                        in long month,
 167                        in long day);
 168
 169     /**
 170      * Format the given time in a human readable format.
 171      *
 172      * See FormatDateTime for details.
 173      */
 174     wstring FormatTime(in wstring locale,
 175                        in long timeFormatSelector,
 176                        in long hour,
 177                        in long minute,
 178                        in long second);
 179 };