gecko-dev/intl/locale/nsIScriptableDateFormat.idl

180 строки
6.4 KiB
Plaintext

/* -*- 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);
};