Line data Source code
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 "nsString.h"
11 : #include "nsTArray.h"
12 : #ifdef ENABLE_INTL_API
13 : #include "unicode/uloc.h"
14 : #endif
15 :
16 : #include "mozIOSPreferences.h"
17 :
18 : namespace mozilla {
19 : namespace intl {
20 :
21 : /**
22 : * OSPreferences API provides a set of methods for retrieving information from
23 : * the host environment on topics such as:
24 : * - Internationalization
25 : * - Localization
26 : * - Regional preferences
27 : *
28 : * The API is meant to remain as simple as possible, relaying information from
29 : * the host environment to the user without too much logic.
30 : *
31 : * Saying that, there are two exceptions to that paradigm.
32 : *
33 : * First one is normalization. We do intend to translate host environment
34 : * concepts to unified Intl/L10n vocabulary used by Mozilla.
35 : * That means that we will format locale IDs, timezone names, currencies etc.
36 : * into a chosen format.
37 : *
38 : * Second is caching. This API does cache values and where possible will
39 : * hook into the environment for some event-driven cache invalidation.
40 : *
41 : * This means that on platforms that do not support a mechanism to
42 : * notify apps about changes, new OS-level settings may not be reflected
43 : * in the app until it is relaunched.
44 : */
45 2 : class OSPreferences: public mozIOSPreferences
46 : {
47 :
48 : public:
49 : NS_DECL_ISUPPORTS
50 : NS_DECL_MOZIOSPREFERENCES
51 :
52 : enum class DateTimeFormatStyle {
53 : Invalid = -1,
54 : None,
55 : Short, // e.g. time: HH:mm, date: Y/m/d
56 : Medium, // likely same as Short
57 : Long, // e.g. time: including seconds, date: including weekday
58 : Full // e.g. time: with timezone, date: with long weekday, month
59 : };
60 :
61 : /**
62 : * Create (if necessary) and return a raw pointer to the singleton instance.
63 : * Use this accessor in C++ code that just wants to call a method on the
64 : * instance, but does not need to hold a reference, as in
65 : * nsAutoCString str;
66 : * OSPreferences::GetInstance()->GetSystemLocale(str);
67 : */
68 : static OSPreferences* GetInstance();
69 :
70 : /**
71 : * Return an addRef'd pointer to the singleton instance. This is used by the
72 : * XPCOM constructor that exists to support usage from JS.
73 : */
74 1 : static already_AddRefed<OSPreferences> GetInstanceAddRefed()
75 : {
76 1 : return RefPtr<OSPreferences>(GetInstance()).forget();
77 : }
78 :
79 :
80 : /**
81 : * Returns a list of locales used by the host environment.
82 : *
83 : * The result is a sorted list and we expect that the OS attempts to
84 : * use the top locale from the list for which it has data.
85 : *
86 : * Each element of the list is a valid locale ID that can be passed to ICU
87 : * and ECMA402 Intl APIs,
88 : * At the same time each element is a valid BCP47 language tag that can be
89 : * used for language negotiation.
90 : *
91 : * Example: ["en-US", "de", "pl", "sr-Cyrl", "zh-Hans-HK"]
92 : *
93 : * The return bool value indicates whether the function successfully
94 : * resolved at least one locale.
95 : *
96 : * Usage:
97 : * nsTArray<nsCString> systemLocales;
98 : * OSPreferences::GetInstance()->GetSystemLocales(systemLocales);
99 : *
100 : * (See mozIOSPreferences.idl for a JS-callable version of this.)
101 : */
102 : bool GetSystemLocales(nsTArray<nsCString>& aRetVal);
103 :
104 : static bool GetDateTimeConnectorPattern(const nsACString& aLocale,
105 : nsAString& aRetVal);
106 :
107 : protected:
108 : nsTArray<nsCString> mSystemLocales;
109 :
110 : private:
111 0 : virtual ~OSPreferences() {};
112 :
113 : static StaticRefPtr<OSPreferences> sInstance;
114 :
115 : static bool CanonicalizeLanguageTag(nsCString& aLoc);
116 :
117 : /**
118 : * Helper methods to get formats from ICU; these will return false
119 : * in case of error, in which case the caller cannot rely on aRetVal.
120 : */
121 : bool GetDateTimePatternForStyle(DateTimeFormatStyle aDateStyle,
122 : DateTimeFormatStyle aTimeStyle,
123 : const nsACString& aLocale,
124 : nsAString& aRetVal);
125 :
126 : bool GetDateTimeSkeletonForStyle(DateTimeFormatStyle aDateStyle,
127 : DateTimeFormatStyle aTimeStyle,
128 : const nsACString& aLocale,
129 : nsAString& aRetVal);
130 :
131 : bool GetPatternForSkeleton(const nsAString& aSkeleton,
132 : const nsACString& aLocale,
133 : nsAString& aRetVal);
134 :
135 : /**
136 : * This is a host environment specific method that will be implemented
137 : * separately for each platform.
138 : *
139 : * It is only called when the cache is empty or invalidated.
140 : *
141 : * The return value indicates whether the function successfully
142 : * resolved at least one locale.
143 : */
144 : bool ReadSystemLocales(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,
162 : nsAString& aRetVal);
163 :
164 : /**
165 : * Triggers a refresh of retrieving data from host environment.
166 : *
167 : * If the result differs from the previous list, it will additionally
168 : * trigger global events for changed values:
169 : *
170 : * * SystemLocales: "intl:system-locales-changed"
171 : *
172 : * This method should not be called from anywhere except of per-platform
173 : * hooks into OS events.
174 : */
175 : void Refresh();
176 : };
177 :
178 : } // intl
179 : } // namespace mozilla
180 :
181 : #endif /* mozilla_intl_IntlOSPreferences_h__ */
|
