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_DRAFT_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 * @draft ICU 51 75 */ 76 static LocaleDisplayNames* U_EXPORT2 createInstance(const Locale& locale, 77 UDisplayContext *contexts, int32_t length); 78 #endif /* U_HIDE_DRAFT_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 * @draft ICU 51 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 198 inline LocaleDisplayNames* LocaleDisplayNames::createInstance(const Locale& locale) { 199 return LocaleDisplayNames::createInstance(locale, ULDN_STANDARD_NAMES); 200 } 201 202 U_NAMESPACE_END 203 204 #endif 205 206 #endif 207
