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
25U_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 */
33class U_I18N_API LocaleDisplayNames : public UObject {
34public:
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
196inline LocaleDisplayNames* LocaleDisplayNames::createInstance(const Locale& locale) {
197  return LocaleDisplayNames::createInstance(locale, ULDN_STANDARD_NAMES);
198}
199
200U_NAMESPACE_END
201
202#endif
203
204#endif
205