intl/locale/OSPreferences.h

   1 /* -*- Mode: C++; 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 #ifndef mozilla_intl_IntlOSPreferences_h__
   7 #define mozilla_intl_IntlOSPreferences_h__
   8
   9 #include "mozilla/StaticPtr.h"
  10 #include "nsDataHashtable.h"
  11 #include "nsString.h"
  12 #include "nsTArray.h"
  13 #include "unicode/uloc.h"
  14
  15 #include "mozIOSPreferences.h"
  16
  17 namespace mozilla {
  18 namespace intl {
  19
  20 /**
  21  * OSPreferences API provides a set of methods for retrieving information from
  22  * the host environment on topics such as:
  23  *   - Internationalization
  24  *   - Localization
  25  *   - Regional preferences
  26  *
  27  * The API is meant to remain as simple as possible, relaying information from
  28  * the host environment to the user without too much logic.
  29  *
  30  * Saying that, there are two exceptions to that paradigm.
  31  *
  32  * First one is normalization. We do intend to translate host environment
  33  * concepts to unified Intl/L10n vocabulary used by Mozilla.
  34  * That means that we will format locale IDs, timezone names, currencies etc.
  35  * into a chosen format.
  36  *
  37  * Second is caching. This API does cache values and where possible will
  38  * hook into the environment for some event-driven cache invalidation.
  39  *
  40  * This means that on platforms that do not support a mechanism to
  41  * notify apps about changes, new OS-level settings may not be reflected
  42  * in the app until it is relaunched.
  43  */
  44 class OSPreferences : public mozIOSPreferences {
  45  public:
  46   NS_DECL_ISUPPORTS
  47   NS_DECL_MOZIOSPREFERENCES
  48
  49   enum class DateTimeFormatStyle {
  50     Invalid = -1,
  51     None,
  52     Short,   // e.g. time: HH:mm, date: Y/m/d
  53     Medium,  // likely same as Short
  54     Long,    // e.g. time: including seconds, date: including weekday
  55     Full     // e.g. time: with timezone, date: with long weekday, month
  56   };
  57
  58   /**
  59    * Constructor, to do any necessary initialization such as registering for
  60    * notifications from the system when prefs are modified.
  61    */
  62   OSPreferences();
  63
  64   /**
  65    * Create (if necessary) and return a raw pointer to the singleton instance.
  66    * Use this accessor in C++ code that just wants to call a method on the
  67    * instance, but does not need to hold a reference, as in
  68    *    nsAutoCString str;
  69    *    OSPreferences::GetInstance()->GetSystemLocale(str);
  70    */
  71   static OSPreferences* GetInstance();
  72
  73   /**
  74    * Return an addRef'd pointer to the singleton instance. This is used by the
  75    * XPCOM constructor that exists to support usage from JS.
  76    */
  77   static already_AddRefed<OSPreferences> GetInstanceAddRefed() {
  78     return RefPtr<OSPreferences>(GetInstance()).forget();
  79   }
  80
  81   static bool GetDateTimeConnectorPattern(const nsACString& aLocale,
  82                                           nsAString& aRetVal);
  83
  84   /**
  85    * Triggers a refresh of retrieving data from host environment.
  86    *
  87    * If the result differs from the previous list, it will additionally
  88    * trigger global events for changed values:
  89    *
  90    *  * SystemLocales: "intl:system-locales-changed"
  91    *
  92    * This method should not be called from anywhere except of per-platform
  93    * hooks into OS events.
  94    */
  95   void Refresh();
  96
  97  protected:
  98   nsTArray<nsCString> mSystemLocales;
  99   nsTArray<nsCString> mRegionalPrefsLocales;
 100
 101   const size_t kMaxCachedPatterns = 15;
 102   nsDataHashtable<nsCStringHashKey, nsString> mPatternCache;
 103
 104  private:
 105   virtual ~OSPreferences();
 106
 107   static StaticRefPtr<OSPreferences> sInstance;
 108
 109   static bool CanonicalizeLanguageTag(nsCString& aLoc);
 110
 111   /**
 112    * Helper methods to get formats from ICU; these will return false
 113    * in case of error, in which case the caller cannot rely on aRetVal.
 114    */
 115   bool GetDateTimePatternForStyle(DateTimeFormatStyle aDateStyle,
 116                                   DateTimeFormatStyle aTimeStyle,
 117                                   const nsACString& aLocale,
 118                                   nsAString& aRetVal);
 119
 120   bool GetDateTimeSkeletonForStyle(DateTimeFormatStyle aDateStyle,
 121                                    DateTimeFormatStyle aTimeStyle,
 122                                    const nsACString& aLocale,
 123                                    nsAString& aRetVal);
 124
 125   bool GetPatternForSkeleton(const nsAString& aSkeleton,
 126                              const nsACString& aLocale, nsAString& aRetVal);
 127
 128   /**
 129    * This is a host environment specific method that will be implemented
 130    * separately for each platform.
 131    *
 132    * It is only called when the cache is empty or invalidated.
 133    *
 134    * The return value indicates whether the function successfully
 135    * resolved at least one locale.
 136    */
 137   bool ReadSystemLocales(nsTArray<nsCString>& aRetVal);
 138
 139   bool ReadRegionalPrefsLocales(nsTArray<nsCString>& aRetVal);
 140
 141   /**
 142    * This is a host environment specific method that will be implemented
 143    * separately for each platform.
 144    *
 145    * It is `best-effort` kind of API that attempts to construct the best
 146    * possible date/time pattern for the given styles and locales.
 147    *
 148    * In case we fail to, or don't know how to retrieve the pattern in a
 149    * given environment this function will return false.
 150    * Callers should always be prepared to handle that scenario.
 151    *
 152    * The heuristic may depend on the OS API and HIG guidelines.
 153    */
 154   bool ReadDateTimePattern(DateTimeFormatStyle aDateFormatStyle,
 155                            DateTimeFormatStyle aTimeFormatStyle,
 156                            const nsACString& aLocale, nsAString& aRetVal);
 157 };
 158
 159 }  // namespace intl
 160 }  // namespace mozilla
 161
 162 #endif /* mozilla_intl_IntlOSPreferences_h__ */