michael@0: /*
michael@0: ******************************************************************************
michael@0: * Copyright (C) 2010-2012, International Business Machines Corporation and
michael@0: * others. All Rights Reserved.
michael@0: ******************************************************************************
michael@0: */
michael@0: 
michael@0: #ifndef LOCDSPNM_H
michael@0: #define LOCDSPNM_H
michael@0: 
michael@0: #include "unicode/utypes.h"
michael@0: 
michael@0: /**
michael@0:  * \file
michael@0:  * \brief C++ API: Provides display names of Locale and its components.
michael@0:  */
michael@0: 
michael@0: #if !UCONFIG_NO_FORMATTING
michael@0: 
michael@0: #include "unicode/locid.h"
michael@0: #include "unicode/uscript.h"
michael@0: #include "unicode/uldnames.h"
michael@0: #include "unicode/udisplaycontext.h"
michael@0: 
michael@0: U_NAMESPACE_BEGIN
michael@0: 
michael@0: /**
michael@0:  * Returns display names of Locales and components of Locales. For
michael@0:  * more information on language, script, region, variant, key, and
michael@0:  * values, see Locale.
michael@0:  * @stable ICU 4.4
michael@0:  */
michael@0: class U_I18N_API LocaleDisplayNames : public UObject {
michael@0: public:
michael@0:     /**
michael@0:      * Destructor.
michael@0:      * @stable ICU 4.4
michael@0:      */
michael@0:     virtual ~LocaleDisplayNames();
michael@0: 
michael@0:     /**
michael@0:      * Convenience overload of
michael@0:      * {@link #createInstance(const Locale& locale, UDialectHandling dialectHandling)}
michael@0:      * that specifies STANDARD dialect handling.
michael@0:      * @param locale the display locale
michael@0:      * @return a LocaleDisplayNames instance
michael@0:      * @stable ICU 4.4
michael@0:      */
michael@0:     static LocaleDisplayNames* U_EXPORT2 createInstance(const Locale& locale);
michael@0: 
michael@0:     /**
michael@0:      * Returns an instance of LocaleDisplayNames that returns names
michael@0:      * formatted for the provided locale, using the provided
michael@0:      * dialectHandling.
michael@0:      *
michael@0:      * @param locale the display locale
michael@0:      * @param dialectHandling how to select names for locales
michael@0:      * @return a LocaleDisplayNames instance
michael@0:      * @stable ICU 4.4
michael@0:      */
michael@0:     static LocaleDisplayNames* U_EXPORT2 createInstance(const Locale& locale,
michael@0:                             UDialectHandling dialectHandling);
michael@0: 
michael@0: #ifndef U_HIDE_DRAFT_API
michael@0:     /**
michael@0:      * Returns an instance of LocaleDisplayNames that returns names formatted
michael@0:      * for the provided locale, using the provided UDisplayContext settings.
michael@0:      *
michael@0:      * @param locale the display locale
michael@0:      * @param contexts List of one or more context settings (e.g. for dialect
michael@0:      *               handling, capitalization, etc.
michael@0:      * @param length Number of items in the contexts list
michael@0:      * @return a LocaleDisplayNames instance
michael@0:      * @draft ICU 51
michael@0:      */
michael@0:     static LocaleDisplayNames* U_EXPORT2 createInstance(const Locale& locale,
michael@0:                             UDisplayContext *contexts, int32_t length);
michael@0: #endif  /* U_HIDE_DRAFT_API */
michael@0: 
michael@0:     // getters for state
michael@0:     /**
michael@0:      * Returns the locale used to determine the display names. This is
michael@0:      * not necessarily the same locale passed to {@link #createInstance}.
michael@0:      * @return the display locale
michael@0:      * @stable ICU 4.4
michael@0:      */
michael@0:     virtual const Locale& getLocale() const = 0;
michael@0: 
michael@0:     /**
michael@0:      * Returns the dialect handling used in the display names.
michael@0:      * @return the dialect handling enum
michael@0:      * @stable ICU 4.4
michael@0:      */
michael@0:     virtual UDialectHandling getDialectHandling() const = 0;
michael@0: 
michael@0:     /**
michael@0:      * Returns the UDisplayContext value for the specified UDisplayContextType.
michael@0:      * @param type the UDisplayContextType whose value to return
michael@0:      * @return the UDisplayContext for the specified type.
michael@0:      * @draft ICU 51
michael@0:      */
michael@0:     virtual UDisplayContext getContext(UDisplayContextType type) const = 0;
michael@0: 
michael@0:     // names for entire locales
michael@0:     /**
michael@0:      * Returns the display name of the provided locale.
michael@0:      * @param locale the locale whose display name to return
michael@0:      * @param result receives the locale's display name
michael@0:      * @return the display name of the provided locale
michael@0:      * @stable ICU 4.4
michael@0:      */
michael@0:     virtual UnicodeString& localeDisplayName(const Locale& locale,
michael@0:                          UnicodeString& result) const = 0;
michael@0: 
michael@0:     /**
michael@0:      * Returns the display name of the provided locale id.
michael@0:      * @param localeId the id of the locale whose display name to return
michael@0:      * @param result receives the locale's display name
michael@0:      * @return the display name of the provided locale
michael@0:      * @stable ICU 4.4
michael@0:      */
michael@0:     virtual UnicodeString& localeDisplayName(const char* localeId,
michael@0:                          UnicodeString& result) const = 0;
michael@0: 
michael@0:     // names for components of a locale id
michael@0:     /**
michael@0:      * Returns the display name of the provided language code.
michael@0:      * @param lang the language code
michael@0:      * @param result receives the language code's display name
michael@0:      * @return the display name of the provided language code
michael@0:      * @stable ICU 4.4
michael@0:      */
michael@0:     virtual UnicodeString& languageDisplayName(const char* lang,
michael@0:                            UnicodeString& result) const = 0;
michael@0: 
michael@0:     /**
michael@0:      * Returns the display name of the provided script code.
michael@0:      * @param script the script code
michael@0:      * @param result receives the script code's display name
michael@0:      * @return the display name of the provided script code
michael@0:      * @stable ICU 4.4
michael@0:      */
michael@0:     virtual UnicodeString& scriptDisplayName(const char* script,
michael@0:                          UnicodeString& result) const = 0;
michael@0: 
michael@0:     /**
michael@0:      * Returns the display name of the provided script code.
michael@0:      * @param scriptCode the script code number
michael@0:      * @param result receives the script code's display name
michael@0:      * @return the display name of the provided script code
michael@0:      * @stable ICU 4.4
michael@0:      */
michael@0:     virtual UnicodeString& scriptDisplayName(UScriptCode scriptCode,
michael@0:                          UnicodeString& result) const = 0;
michael@0: 
michael@0:     /**
michael@0:      * Returns the display name of the provided region code.
michael@0:      * @param region the region code
michael@0:      * @param result receives the region code's display name
michael@0:      * @return the display name of the provided region code
michael@0:      * @stable ICU 4.4
michael@0:      */
michael@0:     virtual UnicodeString& regionDisplayName(const char* region,
michael@0:                          UnicodeString& result) const = 0;
michael@0: 
michael@0:     /**
michael@0:      * Returns the display name of the provided variant.
michael@0:      * @param variant the variant string
michael@0:      * @param result receives the variant's display name
michael@0:      * @return the display name of the provided variant
michael@0:      * @stable ICU 4.4
michael@0:      */
michael@0:     virtual UnicodeString& variantDisplayName(const char* variant,
michael@0:                           UnicodeString& result) const = 0;
michael@0: 
michael@0:     /**
michael@0:      * Returns the display name of the provided locale key.
michael@0:      * @param key the locale key name
michael@0:      * @param result receives the locale key's display name
michael@0:      * @return the display name of the provided locale key
michael@0:      * @stable ICU 4.4
michael@0:      */
michael@0:     virtual UnicodeString& keyDisplayName(const char* key,
michael@0:                       UnicodeString& result) const = 0;
michael@0: 
michael@0:     /**
michael@0:      * Returns the display name of the provided value (used with the provided key).
michael@0:      * @param key the locale key name
michael@0:      * @param value the locale key's value
michael@0:      * @param result receives the value's display name
michael@0:      * @return the display name of the provided value
michael@0:      * @stable ICU 4.4
michael@0:      */
michael@0:     virtual UnicodeString& keyValueDisplayName(const char* key, const char* value,
michael@0:                            UnicodeString& result) const = 0;
michael@0: };
michael@0: 
michael@0: inline LocaleDisplayNames* LocaleDisplayNames::createInstance(const Locale& locale) {
michael@0:   return LocaleDisplayNames::createInstance(locale, ULDN_STANDARD_NAMES);
michael@0: }
michael@0: 
michael@0: U_NAMESPACE_END
michael@0: 
michael@0: #endif
michael@0: 
michael@0: #endif