jars/icu4j-4_4_2-src/main/classes/core/src/com/ibm/icu/text/LocaleDisplayNames.java

   1 /*\r
   2  *******************************************************************************\r
   3  * Copyright (C) 2009-2010, International Business Machines Corporation and    *\r
   4  * others. All Rights Reserved.                                                *\r
   5  *******************************************************************************\r
   6  */\r
   7 package com.ibm.icu.text;\r
   8 \r
   9 import java.util.Locale;\r
  10 \r
  11 import com.ibm.icu.impl.LocaleDisplayNamesImpl;\r
  12 import com.ibm.icu.util.ULocale;\r
  13 \r
  14 /**\r
  15  * Returns display names of ULocales and components of ULocales. For\r
  16  * more information on language, script, region, variant, key, and\r
  17  * values, see {@link com.ibm.icu.util.ULocale}.\r
  18  * @draft ICU 4.4\r
  19  * @provisional This API might change or be removed in a future release.\r
  20  */\r
  21 public abstract class LocaleDisplayNames {\r
  22     /**\r
  23      * Enum used in {@link #getInstance(ULocale, DialectHandling)}.\r
  24      * @draft ICU 4.4\r
  25      * @provisional This API might change or be removed in a future release.\r
  26      */\r
  27     public enum DialectHandling {\r
  28         /**\r
  29          * Use standard names when generating a locale name,\r
  30          * e.g. en_GB displays as 'English (United Kingdom)'.\r
  31          * @draft ICU 4.4\r
  32          * @provisional This API might change or be removed in a future release.\r
  33          */\r
  34         STANDARD_NAMES,\r
  35         /**\r
  36          * Use dialect names when generating a locale name,\r
  37          * e.g. en_GB displays as 'British English'.\r
  38          * @draft ICU 4.4\r
  39          * @provisional This API might change or be removed in a future release.\r
  40          */\r
  41         DIALECT_NAMES\r
  42     }\r
  43 \r
  44     // factory methods\r
  45     /**\r
  46      * Convenience overload of {@link #getInstance(ULocale, DialectHandling)} that specifies\r
  47      * STANDARD dialect handling.\r
  48      * @param locale the display locale\r
  49      * @return a LocaleDisplayNames instance\r
  50      * @draft ICU 4.4\r
  51      * @provisional This API might change or be removed in a future release.\r
  52      */\r
  53     public static LocaleDisplayNames getInstance(ULocale locale) {\r
  54         return getInstance(locale, DialectHandling.STANDARD_NAMES);\r
  55     };\r
  56 \r
  57     /**\r
  58      * Returns an instance of LocaleDisplayNames that returns names formatted for the provided locale,\r
  59      * using the provided dialectHandling.\r
  60      * @param locale the display locale\r
  61      * @param dialectHandling how to select names for locales\r
  62      * @return a LocaleDisplayNames instance\r
  63      * @draft ICU 4.4\r
  64      * @provisional This API might change or be removed in a future release.\r
  65      */\r
  66     public static LocaleDisplayNames getInstance(ULocale locale, DialectHandling dialectHandling) {\r
  67         return LocaleDisplayNamesImpl.getInstance(locale, dialectHandling);\r
  68     }\r
  69 \r
  70     // getters for state\r
  71     /**\r
  72      * Returns the locale used to determine the display names. This is not necessarily the same\r
  73      * locale passed to {@link #getInstance}.\r
  74      * @return the display locale\r
  75      * @draft ICU 4.4\r
  76      * @provisional This API might change or be removed in a future release.\r
  77      */\r
  78     public abstract ULocale getLocale();\r
  79 \r
  80     /**\r
  81      * Returns the dialect handling used in the display names.\r
  82      * @return the dialect handling enum\r
  83      * @draft ICU 4.4\r
  84      * @provisional This API might change or be removed in a future release.\r
  85      */\r
  86     public abstract DialectHandling getDialectHandling();\r
  87 \r
  88     // names for entire locales\r
  89     /**\r
  90      * Returns the display name of the provided ulocale.\r
  91      * @param locale the locale whose display name to return\r
  92      * @return the display name of the provided locale\r
  93      * @draft ICU 4.4\r
  94      * @provisional This API might change or be removed in a future release.\r
  95      */\r
  96     public abstract String localeDisplayName(ULocale locale);\r
  97 \r
  98     /**\r
  99      * Returns the display name of the provided locale.\r
 100      * @param locale the locale whose display name to return\r
 101      * @return the display name of the provided locale\r
 102      * @draft ICU 4.4\r
 103      * @provisional This API might change or be removed in a future release.\r
 104      */\r
 105     public abstract String localeDisplayName(Locale locale);\r
 106 \r
 107     /**\r
 108      * Returns the display name of the provided locale id.\r
 109      * @param localeId the id of the locale whose display name to return\r
 110      * @return the display name of the provided locale\r
 111      * @draft ICU 4.4\r
 112      * @provisional This API might change or be removed in a future release.\r
 113      */\r
 114     public abstract String localeDisplayName(String localeId);\r
 115 \r
 116     // names for components of a locale id\r
 117     /**\r
 118      * Returns the display name of the provided language code.\r
 119      * @param lang the language code\r
 120      * @return the display name of the provided language code\r
 121      * @draft ICU 4.4\r
 122      * @provisional This API might change or be removed in a future release.\r
 123      */\r
 124     public abstract String languageDisplayName(String lang);\r
 125 \r
 126     /**\r
 127      * Returns the display name of the provided script code.\r
 128      * @param script the script code\r
 129      * @return the display name of the provided script code\r
 130      * @draft ICU 4.4\r
 131      * @provisional This API might change or be removed in a future release.\r
 132      */\r
 133     public abstract String scriptDisplayName(String script);\r
 134 \r
 135     /**\r
 136      * Returns the display name of the provided script code.  See\r
 137      * {@link com.ibm.icu.lang.UScript} for recognized script codes.\r
 138      * @param scriptCode the script code number\r
 139      * @return the display name of the provided script code\r
 140      * @draft ICU 4.4\r
 141      * @provisional This API might change or be removed in a future release.\r
 142      */\r
 143     public abstract String scriptDisplayName(int scriptCode);\r
 144 \r
 145     /**\r
 146      * Returns the display name of the provided region code.\r
 147      * @param region the region code\r
 148      * @return the display name of the provided region code\r
 149      * @draft ICU 4.4\r
 150      * @provisional This API might change or be removed in a future release.\r
 151      */\r
 152     public abstract String regionDisplayName(String region);\r
 153 \r
 154     /**\r
 155      * Returns the display name of the provided variant.\r
 156      * @param variant the variant string\r
 157      * @return the display name of the provided variant\r
 158      * @draft ICU 4.4\r
 159      * @provisional This API might change or be removed in a future release.\r
 160      */\r
 161     public abstract String variantDisplayName(String variant);\r
 162 \r
 163     /**\r
 164      * Returns the display name of the provided locale key.\r
 165      * @param key the locale key name\r
 166      * @return the display name of the provided locale key\r
 167      * @draft ICU 4.4\r
 168      * @provisional This API might change or be removed in a future release.\r
 169      */\r
 170     public abstract String keyDisplayName(String key);\r
 171 \r
 172     /**\r
 173      * Returns the display name of the provided value (used with the provided key).\r
 174      * @param key the locale key name\r
 175      * @param value the locale key's value\r
 176      * @return the display name of the provided value\r
 177      * @draft ICU 4.4\r
 178      * @provisional This API might change or be removed in a future release.\r
 179      */\r
 180     public abstract String keyValueDisplayName(String key, String value);\r
 181 \r
 182     /**\r
 183      * Sole constructor.  (For invocation by subclass constructors,\r
 184      * typically implicit.)\r
 185      * @internal\r
 186      * @deprecated This API is ICU internal only.\r
 187      */\r
 188     protected LocaleDisplayNames() {\r
 189     }\r
 190 }\r