intl/locale/mozIOSPreferences.idl

   1 /* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   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 %{C++
   9 // Define Contractid and CID
  10 #define MOZ_OSPREFERENCES_CID \
  11   { 0x65944815, 0xe9ae, 0x48bd, { 0xa2, 0xbf, 0xf1, 0x10, 0x87, 0x20, 0x95, 0x0c } }
  12
  13 #define MOZ_OSPREFERENCES_CONTRACTID "@mozilla.org/intl/ospreferences;1"
  14 %}
  15
  16 [scriptable, uuid(65944815-e9ae-48bd-a2bf-f1108720950c)]
  17 interface mozIOSPreferences : nsISupports
  18 {
  19   const long dateTimeFormatStyleNone     = 0;
  20   const long dateTimeFormatStyleShort    = 1;
  21   const long dateTimeFormatStyleMedium   = 2;
  22   const long dateTimeFormatStyleLong     = 3;
  23   const long dateTimeFormatStyleFull     = 4;
  24
  25   /**
  26    * Returns a list of locales used by the host environment for UI
  27    * localization.
  28    *
  29    * The result is a sorted list and we expect that the OS attempts to
  30    * use the top locale from the list for which it has data.
  31    *
  32    * Each element of the list is a valid locale ID that can be passed to ICU
  33    * and ECMA402 Intl APIs,
  34    * At the same time each element is a valid BCP47 language tag that can be
  35    * used for language negotiation.
  36    *
  37    * Example: ["en-US", "de", "pl", "sr-Cyrl", "zh-Hans-HK"]
  38    */
  39   readonly attribute Array<ACString> systemLocales;
  40
  41   /**
  42    * Returns a list of locales used by host environment for regional
  43    * preferences internationalization.
  44    *
  45    * The result is a sorted list and we expect that the OS attempts to
  46    * use the top locale from the list for which it has data.
  47    *
  48    * Each element of the list is a valid locale ID that can be passed to ICU
  49    * and ECMA402 Intl APIs,
  50    *
  51    * Example: ["en-US", "de", "pl", "sr-Cyrl", "zh-Hans-HK"]
  52    */
  53   readonly attribute Array<ACString> regionalPrefsLocales;
  54
  55   /**
  56    * Returns the best locale that the host environment is localized to.
  57    *
  58    * The result is a valid locale ID and it should be
  59    * used for all APIs that do not handle language negotiation.
  60    *
  61    * In any scenario involving language negotiation, systemLocales should
  62    * be preferred over the single value.
  63    *
  64    * Example: "zh-Hans-HK"
  65    */
  66   readonly attribute ACString systemLocale;
  67
  68   /**
  69    * Returns the best possible date/time pattern for the host environment
  70    * taking into account date/time regional settings user defined in the OS
  71    * preferences.
  72    *
  73    * Notice, that depending on the OS it may take into account those settings
  74    * for all locales, or only if the locale matches the OS locale.
  75    *
  76    * It takes two integer arguments that must be valid `dateTimeFormatStyle*`
  77    * values (see constants defined above), and a string representing a
  78    * BCP47 locale.
  79    *
  80    * It returns a string with a LDML date/time pattern.
  81    *
  82    * If no pattern can be retrieved from the host environment, it will
  83    * lookup the best available pattern from ICU.
  84    *
  85    * Notice, this is a pretty unique method in this API in that it does
  86    * more than look up into host environment.
  87    * The reason for that is that constructing the right date/time pattern
  88    * requires a lot of OS-specific logic and it ends up being easier to just
  89    * handle all scenarios, including with cases where we fail to retrieve
  90    * anything from the OS, here.
  91    */
  92   AUTF8String getDateTimePattern(in long timeFormatStyle,
  93                                  in long dateFormatStyle,
  94                                  [optional] in ACString locale);
  95 };