1 /*
2 ******************************************************************************
3 * Copyright (C) 2010-2012, International Business Machines Corporation and
4 * others. All Rights Reserved.
5 ******************************************************************************
6 */
7
8 #ifndef LOCDSPNM_H
9 #define LOCDSPNM_H
10
11 #include "unicode/utypes.h"
12
13 /**
14 * \file
15 * \brief C++ API: Provides display names of Locale and its components.
16 */
17
18 #if !UCONFIG_NO_FORMATTING
19
20 #include "unicode/locid.h"
21 #include "unicode/uscript.h"
22 #include "unicode/uldnames.h"
23 #include "unicode/udisplaycontext.h"
24
25 U_NAMESPACE_BEGIN
26
27 /**
28 * Returns display names of Locales and components of Locales. For
29 * more information on language, script, region, variant, key, and
30 * values, see Locale.
31 * @stable ICU 4.4
32 */
33 class U_I18N_API LocaleDisplayNames : public UObject {
34 public:
35 /**
36 * Destructor.
37 * @stable ICU 4.4
38 */
39 virtual ~LocaleDisplayNames();
40
41 /**
42 * Convenience overload of
43 * {@link #createInstance(const Locale& locale, UDialectHandling dialectHandling)}
44 * that specifies STANDARD dialect handling.
45 * @param locale the display locale
46 * @return a LocaleDisplayNames instance
47 * @stable ICU 4.4
48 */
49 static LocaleDisplayNames* U_EXPORT2 createInstance(const Locale& locale);
50
51 /**
52 * Returns an instance of LocaleDisplayNames that returns names
53 * formatted for the provided locale, using the provided
54 * dialectHandling.
55 *
56 * @param locale the display locale
57 * @param dialectHandling how to select names for locales
58 * @return a LocaleDisplayNames instance
59 * @stable ICU 4.4
60 */
61 static LocaleDisplayNames* U_EXPORT2 createInstance(const Locale& locale,
62 UDialectHandling dialectHandling);
63
64 #ifndef U_HIDE_INTERNAL_API
65 /**
66 * Returns an instance of LocaleDisplayNames that returns names formatted
67 * for the provided locale, using the provided UDisplayContext settings.
68 *
69 * @param locale the display locale
70 * @param contexts List of one or more context settings (e.g. for dialect
71 * handling, capitalization, etc.
72 * @param length Number of items in the contexts list
73 * @return a LocaleDisplayNames instance
74 * @internal ICU 50 technology preview
75 */
76 static LocaleDisplayNames* U_EXPORT2 createInstance(const Locale& locale,
77 UDisplayContext *contexts, int32_t length);
78 #endif /* U_HIDE_INTERNAL_API */
79
80 // getters for state
81 /**
82 * Returns the locale used to determine the display names. This is
83 * not necessarily the same locale passed to {@link #createInstance}.
84 * @return the display locale
85 * @stable ICU 4.4
86 */
87 virtual const Locale& getLocale() const = 0;
88
89 /**
90 * Returns the dialect handling used in the display names.
91 * @return the dialect handling enum
92 * @stable ICU 4.4
93 */
94 virtual UDialectHandling getDialectHandling() const = 0;
95
96 /**
97 * Returns the UDisplayContext value for the specified UDisplayContextType.
98 * @param type the UDisplayContextType whose value to return
99 * @return the UDisplayContext for the specified type.
100 * @internal ICU 50 technology preview
101 */
102 virtual UDisplayContext getContext(UDisplayContextType type) const = 0;
103
104 // names for entire locales
105 /**
106 * Returns the display name of the provided locale.
107 * @param locale the locale whose display name to return
108 * @param result receives the locale's display name
109 * @return the display name of the provided locale
110 * @stable ICU 4.4
111 */
112 virtual UnicodeString& localeDisplayName(const Locale& locale,
113 UnicodeString& result) const = 0;
114
115 /**
116 * Returns the display name of the provided locale id.
117 * @param localeId the id of the locale whose display name to return
118 * @param result receives the locale's display name
119 * @return the display name of the provided locale
120 * @stable ICU 4.4
121 */
122 virtual UnicodeString& localeDisplayName(const char* localeId,
123 UnicodeString& result) const = 0;
124
125 // names for components of a locale id
126 /**
127 * Returns the display name of the provided language code.
128 * @param lang the language code
129 * @param result receives the language code's display name
130 * @return the display name of the provided language code
131 * @stable ICU 4.4
132 */
133 virtual UnicodeString& languageDisplayName(const char* lang,
134 UnicodeString& result) const = 0;
135
136 /**
137 * Returns the display name of the provided script code.
138 * @param script the script code
139 * @param result receives the script code's display name
140 * @return the display name of the provided script code
141 * @stable ICU 4.4
142 */
143 virtual UnicodeString& scriptDisplayName(const char* script,
144 UnicodeString& result) const = 0;
145
146 /**
147 * Returns the display name of the provided script code.
148 * @param scriptCode the script code number
149 * @param result receives the script code's display name
150 * @return the display name of the provided script code
151 * @stable ICU 4.4
152 */
153 virtual UnicodeString& scriptDisplayName(UScriptCode scriptCode,
154 UnicodeString& result) const = 0;
155
156 /**
157 * Returns the display name of the provided region code.
158 * @param region the region code
159 * @param result receives the region code's display name
160 * @return the display name of the provided region code
161 * @stable ICU 4.4
162 */
163 virtual UnicodeString& regionDisplayName(const char* region,
164 UnicodeString& result) const = 0;
165
166 /**
167 * Returns the display name of the provided variant.
168 * @param variant the variant string
169 * @param result receives the variant's display name
170 * @return the display name of the provided variant
171 * @stable ICU 4.4
172 */
173 virtual UnicodeString& variantDisplayName(const char* variant,
174 UnicodeString& result) const = 0;
175
176 /**
177 * Returns the display name of the provided locale key.
178 * @param key the locale key name
179 * @param result receives the locale key's display name
180 * @return the display name of the provided locale key
181 * @stable ICU 4.4
182 */
183 virtual UnicodeString& keyDisplayName(const char* key,
184 UnicodeString& result) const = 0;
185
186 /**
187 * Returns the display name of the provided value (used with the provided key).
188 * @param key the locale key name
189 * @param value the locale key's value
190 * @param result receives the value's display name
191 * @return the display name of the provided value
192 * @stable ICU 4.4
193 */
194 virtual UnicodeString& keyValueDisplayName(const char* key, const char* value,
195 UnicodeString& result) const = 0;
196
197 private:
198 // No ICU "poor man's RTTI" for this class nor its subclasses.
199 virtual UClassID getDynamicClassID() const;
200 };
201
createInstance(const Locale & locale)202 inline LocaleDisplayNames* LocaleDisplayNames::createInstance(const Locale& locale) {
203 return LocaleDisplayNames::createInstance(locale, ULDN_STANDARD_NAMES);
204 }
205
206 U_NAMESPACE_END
207
208 #endif
209
210 #endif
211