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