summaryrefslogtreecommitdiff
path: root/intl/locale/nsIScriptableDateFormat.idl
blob: 04dcbe333fc493f58ae70495e0798faf2272a218 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsISupports.idl"

typedef long nsDateFormatSelector;
%{ C++
enum
{
    kDateFormatNone = 0,            // do not include the date  in the format string
    kDateFormatLong,                // provides the long date format for the given locale
    kDateFormatShort,               // provides the short date format for the given locale
    kDateFormatYearMonth,           // formats using only the year and month 
    kDateFormatWeekday              // week day (e.g. Mon, Tue)
};
%}

typedef long nsTimeFormatSelector;
%{ C++
enum
{
    kTimeFormatNone = 0,            // don't include the time in the format string
    kTimeFormatSeconds,             // provides the time format with seconds in the  given locale 
    kTimeFormatNoSeconds,           // provides the time format without seconds in the given locale 
    kTimeFormatSecondsForce24Hour,  // forces the time format to use the 24 clock, regardless of the locale conventions
    kTimeFormatNoSecondsForce24Hour // forces the time format to use the 24 clock, regardless of the locale conventions
};
%}

%{C++
// Define Contractid and CID
// {2EA2E7D0-4095-11d3-9144-006008A6EDF6}
#define NS_SCRIPTABLEDATEFORMAT_CID \
{ 0x2ea2e7d0, 0x4095, 0x11d3, { 0x91, 0x44, 0x0, 0x60, 0x8, 0xa6, 0xed, 0xf6 } }

#define NS_SCRIPTABLEDATEFORMAT_CONTRACTID "@mozilla.org/intl/scriptabledateformat;1"

extern nsresult
NS_NewScriptableDateFormat(nsISupports* aOuter, REFNSIID aIID, void** aResult);
%}

/**
 * Format date and time in a human readable format.
 */
[scriptable, uuid(0c89efb0-1aae-11d3-9141-006008a6edf6)]
interface nsIScriptableDateFormat : nsISupports
{
    /**
     * Do not include the date in the format string.
     */
    const long dateFormatNone = 0;

    /**
     * Provide the long date format.
     *
     * NOTE:
     * The original definitions of dateFormatLong and dateFormatShort are from
     * the Windows platform. 
     * In US English dateFormatLong output will be like:
     *     Wednesday, January 29, 2003 4:02:14 PM
     * In US English dateFormatShort output will be like:
     *     1/29/03 4:02:14 PM
     * On platforms like Linux, it is rather difficult to achieve exact
     * same output, and since we are aiming at human readers, it does not make
     * sense to achieve exact same result. We will do just enough as the
     * platform allow us to do. 
     */
    const long dateFormatLong = 1;

    /**
     * Provide the short date format. See also dateFormatLong.
     */
    const long dateFormatShort = 2;

    /**
     * Format using only the year and month.
     */
    const long dateFormatYearMonth = 3;

    /**
     * Provide the Week day (e.g. Mo, Mon, Monday or similar).
     */
    const long dateFormatWeekday = 4;

    /**
     * Don't include the time in the format string.
     */
    const long timeFormatNone = 0;

    /**
     * Provide the time format with seconds.
     */
    const long timeFormatSeconds = 1;

    /**
     * Provide the time format without seconds.
     */
    const long timeFormatNoSeconds = 2;

    /**
     * Provide the time format with seconds, and force the time format to use
     * 24-hour clock, regardless of the locale conventions.
     */
    const long timeFormatSecondsForce24Hour = 3;

    /**
     * Provide the time format without seconds, and force the time format to use
     * 24-hour clock, regardless of the locale conventions.
     */
    const long timeFormatNoSecondsForce24Hour = 4;

    /**
     * Format the given date and time in a human readable format.
     *
     * The underlying operating system is used to format the date and time.
     *
     * Pass an empty string as the locale parameter to use the OS settings with
     * the preferred date and time formatting given by the user.
     *
     * Pass a locale code as described in nsILocale as the locale parameter
     * (e.g. en-US) to use a specific locale. If the given locale is not
     * available, a fallback will be used.
     *
     * NOTE: The output of this method depends on the operating system and user
     * settings. Even if you pass a locale code as the first parameter, there
     * are no guarantees about which locale and exact format the returned value
     * uses. Even if you know the locale, the format might be customized by the
     * user. Therefore you should not use the returned values in contexts where
     * you depend on any specific format or language.
     *
     * @param locale
     *        Locale code of locale used to format the date or an empty string
     *        to follow user preference.
     * @param dateFormatSelector
     *        Indicate which format should preferably be used for the date.
     *        Use one of the dateFormat* constants.
     * @param timeFormatSelector
     *        Indicate which format should preferably be used for the time.
     *        Use one of the timeFormat* constants.
     * @param year, month, day, hour, minute and second
     *        The date and time to be formatted, given in the computer's local
     *        time zone.
     * @return The date and time formatted as human readable text according to
     *         user preferences or the given locale.
     */
    wstring FormatDateTime(in wstring locale, 
                           in long dateFormatSelector, 
                           in long timeFormatSelector,
                           in long year, 
                           in long month, 
                           in long day, 
                           in long hour, 
                           in long minute, 
                           in long second);

    /**
     * Format the given date in a human readable format.
     *
     * See FormatDateTime for details.
     */
    wstring FormatDate(in wstring locale, 
                       in long dateFormatSelector, 
                       in long year, 
                       in long month, 
                       in long day);

    /**
     * Format the given time in a human readable format.
     *
     * See FormatDateTime for details.
     */
    wstring FormatTime(in wstring locale, 
                       in long timeFormatSelector,
                       in long hour, 
                       in long minute, 
                       in long second);
};