gecko/intl/locale/idl/nsIScriptableDateFormat.idl

/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/* ***** BEGIN LICENSE BLOCK *****
 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
 *
 * The contents of this file are subject to the Mozilla Public License Version
 * 1.1 (the "License"); you may not use this file except in compliance with
 * the License. You may obtain a copy of the License at
 * http://www.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS IS" basis,
 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
 * for the specific language governing rights and limitations under the
 * License.
 *
 * The Original Code is mozilla.org code.
 *
 * The Initial Developer of the Original Code is
 * Netscape Communications Corporation.
 * Portions created by the Initial Developer are Copyright (C) 1998
 * the Initial Developer. All Rights Reserved.
 *
 * Contributor(s):
 *
 * Alternatively, the contents of this file may be used under the terms of
 * either of the GNU General Public License Version 2 or later (the "GPL"),
 * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
 * in which case the provisions of the GPL or the LGPL are applicable instead
 * of those above. If you wish to allow use of your version of this file only
 * under the terms of either the GPL or the LGPL, and not to allow others to
 * use your version of this file under the terms of the MPL, indicate your
 * decision by deleting the provisions above and replace them with the notice
 * and other provisions required by the GPL or the LGPL. If you do not delete
 * the provisions above, a recipient may use your version of this file under
 * the terms of any one of the MPL, the GPL or the LGPL.
 *
 * ***** END LICENSE BLOCK ***** */

#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 NS_IMETHODIMP
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 and OS2, 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);
};