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
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#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
198inline LocaleDisplayNames* LocaleDisplayNames::createInstance(const Locale& locale) {
199  return LocaleDisplayNames::createInstance(locale, ULDN_STANDARD_NAMES);
200}
201
202U_NAMESPACE_END
203
204#endif
205
206#endif
207