icuSources/i18n/unicode/locdspnm.h

   1 /*
   2 ******************************************************************************
   3 * Copyright (C) 2010, 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
  24 U_NAMESPACE_BEGIN
  25
  26 /**
  27  * Returns display names of Locales and components of Locales. For
  28  * more information on language, script, region, variant, key, and
  29  * values, see Locale.
  30  * @stable ICU 4.4
  31  */
  32 class U_I18N_API LocaleDisplayNames : public UObject {
  33 public:
  34     /**
  35      * Destructor.
  36      * @stable ICU 4.4
  37      */
  38     virtual ~LocaleDisplayNames();
  39
  40     /**
  41      * Convenience overload of
  42      * {@link #createInstance(const Locale& locale, UDialectHandling dialectHandling)}
  43      * that specifies STANDARD dialect handling.
  44      * @param locale the display locale
  45      * @return a LocaleDisplayNames instance
  46      * @stable ICU 4.4
  47      */
  48     static LocaleDisplayNames* U_EXPORT2 createInstance(const Locale& locale);
  49
  50     /**
  51      * Returns an instance of LocaleDisplayNames that returns names
  52      * formatted for the provided locale, using the provided
  53      * dialectHandling.
  54      *
  55      * @param locale the display locale
  56      * @param dialectHandling how to select names for locales
  57      * @return a LocaleDisplayNames instance
  58      * @stable ICU 4.4
  59      */
  60     static LocaleDisplayNames* U_EXPORT2 createInstance(const Locale& locale,
  61                                                         UDialectHandling dialectHandling);
  62
  63     // getters for state
  64     /**
  65      * Returns the locale used to determine the display names. This is
  66      * not necessarily the same locale passed to {@link #getInstance}.
  67      * @return the display locale
  68      * @stable ICU 4.4
  69      */
  70     virtual const Locale& getLocale() const = 0;
  71
  72     /**
  73      * Returns the dialect handling used in the display names.
  74      * @return the dialect handling enum
  75      * @stable ICU 4.4
  76      */
  77     virtual UDialectHandling getDialectHandling() const = 0;
  78
  79     // names for entire locales
  80     /**
  81      * Returns the display name of the provided locale.
  82      * @param locale the locale whose display name to return
  83      * @param result receives the locale's display name
  84      * @return the display name of the provided locale
  85      * @stable ICU 4.4
  86      */
  87     virtual UnicodeString& localeDisplayName(const Locale& locale,
  88                                              UnicodeString& result) const = 0;
  89
  90     /**
  91      * Returns the display name of the provided locale id.
  92      * @param localeId the id of the locale whose display name to return
  93      * @param result receives the locale's display name
  94      * @return the display name of the provided locale
  95      * @stable ICU 4.4
  96      */
  97     virtual UnicodeString& localeDisplayName(const char* localeId,
  98                                              UnicodeString& result) const = 0;
  99
 100     // names for components of a locale id
 101     /**
 102      * Returns the display name of the provided language code.
 103      * @param lang the language code
 104      * @param result receives the language code's display name
 105      * @return the display name of the provided language code
 106      * @stable ICU 4.4
 107      */
 108     virtual UnicodeString& languageDisplayName(const char* lang,
 109                                                UnicodeString& result) const = 0;
 110
 111     /**
 112      * Returns the display name of the provided script code.
 113      * @param script the script code
 114      * @param result receives the script code's display name
 115      * @return the display name of the provided script code
 116      * @stable ICU 4.4
 117      */
 118     virtual UnicodeString& scriptDisplayName(const char* script,
 119                                              UnicodeString& result) const = 0;
 120
 121     /**
 122      * Returns the display name of the provided script code.
 123      * @param scriptCode the script code number
 124      * @param result receives the script code's display name
 125      * @return the display name of the provided script code
 126      * @stable ICU 4.4
 127      */
 128     virtual UnicodeString& scriptDisplayName(UScriptCode scriptCode,
 129                                              UnicodeString& result) const = 0;
 130
 131     /**
 132      * Returns the display name of the provided region code.
 133      * @param region the region code
 134      * @param result receives the region code's display name
 135      * @return the display name of the provided region code
 136      * @stable ICU 4.4
 137      */
 138     virtual UnicodeString& regionDisplayName(const char* region,
 139                                              UnicodeString& result) const = 0;
 140
 141     /**
 142      * Returns the display name of the provided variant.
 143      * @param variant the variant string
 144      * @param result receives the variant's display name
 145      * @return the display name of the provided variant
 146      * @stable ICU 4.4
 147      */
 148     virtual UnicodeString& variantDisplayName(const char* variant,
 149                                               UnicodeString& result) const = 0;
 150
 151     /**
 152      * Returns the display name of the provided locale key.
 153      * @param key the locale key name
 154      * @param result receives the locale key's display name
 155      * @return the display name of the provided locale key
 156      * @stable ICU 4.4
 157      */
 158     virtual UnicodeString& keyDisplayName(const char* key,
 159                                           UnicodeString& result) const = 0;
 160
 161     /**
 162      * Returns the display name of the provided value (used with the provided key).
 163      * @param key the locale key name
 164      * @param value the locale key's value
 165      * @param result receives the value's display name
 166      * @return the display name of the provided value
 167      * @stable ICU 4.4
 168      */
 169     virtual UnicodeString& keyValueDisplayName(const char* key, const char* value,
 170                                                UnicodeString& result) const = 0;
 171
 172 private:
 173     // No ICU "poor man's RTTI" for this class nor its subclasses.
 174     virtual UClassID getDynamicClassID() const;
 175 };
 176
 177 inline LocaleDisplayNames::~LocaleDisplayNames() {
 178 }
 179
 180 inline LocaleDisplayNames* LocaleDisplayNames::createInstance(const Locale& locale) {
 181   return LocaleDisplayNames::createInstance(locale, ULDN_STANDARD_NAMES);
 182 }
 183
 184 U_NAMESPACE_END
 185
 186 #endif
 187
 188 #endif