1 /* 2 ****************************************************************************** 3 * Copyright (C) 2010-2014, 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 /** 65 * Returns an instance of LocaleDisplayNames that returns names formatted 66 * for the provided locale, using the provided UDisplayContext settings. 67 * 68 * @param locale the display locale 69 * @param contexts List of one or more context settings (e.g. for dialect 70 * handling, capitalization, etc. 71 * @param length Number of items in the contexts list 72 * @return a LocaleDisplayNames instance 73 * @stable ICU 51 74 */ 75 static LocaleDisplayNames* U_EXPORT2 createInstance(const Locale& locale, 76 UDisplayContext *contexts, int32_t length); 77 78 // getters for state 79 /** 80 * Returns the locale used to determine the display names. This is 81 * not necessarily the same locale passed to {@link #createInstance}. 82 * @return the display locale 83 * @stable ICU 4.4 84 */ 85 virtual const Locale& getLocale() const = 0; 86 87 /** 88 * Returns the dialect handling used in the display names. 89 * @return the dialect handling enum 90 * @stable ICU 4.4 91 */ 92 virtual UDialectHandling getDialectHandling() const = 0; 93 94 /** 95 * Returns the UDisplayContext value for the specified UDisplayContextType. 96 * @param type the UDisplayContextType whose value to return 97 * @return the UDisplayContext for the specified type. 98 * @stable ICU 51 99 */ 100 virtual UDisplayContext getContext(UDisplayContextType type) const = 0; 101 102 // names for entire locales 103 /** 104 * Returns the display name of the provided locale. 105 * @param locale the locale whose display name to return 106 * @param result receives the locale's display name 107 * @return the display name of the provided locale 108 * @stable ICU 4.4 109 */ 110 virtual UnicodeString& localeDisplayName(const Locale& locale, 111 UnicodeString& result) const = 0; 112 113 /** 114 * Returns the display name of the provided locale id. 115 * @param localeId the id of the locale whose display name to return 116 * @param result receives the locale's display name 117 * @return the display name of the provided locale 118 * @stable ICU 4.4 119 */ 120 virtual UnicodeString& localeDisplayName(const char* localeId, 121 UnicodeString& result) const = 0; 122 123 // names for components of a locale id 124 /** 125 * Returns the display name of the provided language code. 126 * @param lang the language code 127 * @param result receives the language code's display name 128 * @return the display name of the provided language code 129 * @stable ICU 4.4 130 */ 131 virtual UnicodeString& languageDisplayName(const char* lang, 132 UnicodeString& result) const = 0; 133 134 /** 135 * Returns the display name of the provided script code. 136 * @param script the script code 137 * @param result receives the script code's display name 138 * @return the display name of the provided script code 139 * @stable ICU 4.4 140 */ 141 virtual UnicodeString& scriptDisplayName(const char* script, 142 UnicodeString& result) const = 0; 143 144 /** 145 * Returns the display name of the provided script code. 146 * @param scriptCode the script code number 147 * @param result receives the script code's display name 148 * @return the display name of the provided script code 149 * @stable ICU 4.4 150 */ 151 virtual UnicodeString& scriptDisplayName(UScriptCode scriptCode, 152 UnicodeString& result) const = 0; 153 154 /** 155 * Returns the display name of the provided region code. 156 * @param region the region code 157 * @param result receives the region code's display name 158 * @return the display name of the provided region code 159 * @stable ICU 4.4 160 */ 161 virtual UnicodeString& regionDisplayName(const char* region, 162 UnicodeString& result) const = 0; 163 164 /** 165 * Returns the display name of the provided variant. 166 * @param variant the variant string 167 * @param result receives the variant's display name 168 * @return the display name of the provided variant 169 * @stable ICU 4.4 170 */ 171 virtual UnicodeString& variantDisplayName(const char* variant, 172 UnicodeString& result) const = 0; 173 174 /** 175 * Returns the display name of the provided locale key. 176 * @param key the locale key name 177 * @param result receives the locale key's display name 178 * @return the display name of the provided locale key 179 * @stable ICU 4.4 180 */ 181 virtual UnicodeString& keyDisplayName(const char* key, 182 UnicodeString& result) const = 0; 183 184 /** 185 * Returns the display name of the provided value (used with the provided key). 186 * @param key the locale key name 187 * @param value the locale key's value 188 * @param result receives the value's display name 189 * @return the display name of the provided value 190 * @stable ICU 4.4 191 */ 192 virtual UnicodeString& keyValueDisplayName(const char* key, const char* value, 193 UnicodeString& result) const = 0; 194 }; 195 196 inline LocaleDisplayNames* LocaleDisplayNames::createInstance(const Locale& locale) { 197 return LocaleDisplayNames::createInstance(locale, ULDN_STANDARD_NAMES); 198 } 199 200 U_NAMESPACE_END 201 202 #endif 203 204 #endif 205
