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
8typedef long nsDateFormatSelector;
9%{ C++
10enum
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
20typedef long nsTimeFormatSelector;
21%{ C++
22enum
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
40extern nsresult
41NS_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)]
48interface 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};
180