icuSources/i18n/unicode/locdspnm.h

   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