1. /*
  2. * @(#)InputMethodDescriptor.java 1.10 03/01/23
  3. *
  4. * Copyright 2003 Sun Microsystems, Inc. All rights reserved.
  5. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
  6. */
  7. package java.awt.im.spi;
  8. import java.awt.AWTException;
  9. import java.awt.Image;
  10. import java.util.Locale;
  11. /**
  12. * Defines methods that provide sufficient information about an input method
  13. * to enable selection and loading of that input method.
  14. * The input method itself is only loaded when it is actually used.
  15. *
  16. * @since 1.3
  17. */
  18. public interface InputMethodDescriptor {
  19. /**
  20. * Returns the locales supported by the corresponding input method.
  21. * The locale may describe just the language, or may also include
  22. * country and variant information if needed.
  23. * The information is used to select input methods by locale
  24. * ({@link java.awt.im.InputContext#selectInputMethod(Locale)}). It may also
  25. * be used to sort input methods by locale in a user-visible
  26. * list of input methods.
  27. * <p>
  28. * Only the input method's primary locales should be returned.
  29. * For example, if a Japanese input method also has a pass-through
  30. * mode for Roman characters, typically still only Japanese would
  31. * be returned. Thus, the list of locales returned is typically
  32. * a subset of the locales for which the corresponding input method's
  33. * implementation of {@link java.awt.im.spi.InputMethod#setLocale} returns true.
  34. * <p>
  35. * If {@link #hasDynamicLocaleList} returns true, this method is
  36. * called each time the information is needed. This
  37. * gives input methods that depend on network resources the chance
  38. * to add or remove locales as resources become available or
  39. * unavailable.
  40. *
  41. * @return the locales supported by the input method
  42. * @exception AWTException if it can be determined that the input method
  43. * is inoperable, for example, because of incomplete installation.
  44. */
  45. Locale[] getAvailableLocales() throws AWTException;
  46. /**
  47. * Returns whether the list of available locales can change
  48. * at runtime. This may be the case, for example, for adapters
  49. * that access real input methods over the network.
  50. */
  51. boolean hasDynamicLocaleList();
  52. /**
  53. * Returns the user-visible name of the corresponding
  54. * input method for the given input locale in the language in which
  55. * the name will be displayed.
  56. * <p>
  57. * The inputLocale parameter specifies the locale for which text
  58. * is input.
  59. * This parameter can only take values obtained from this descriptor's
  60. * {@link #getAvailableLocales} method or null. If it is null, an
  61. * input locale independent name for the input method should be
  62. * returned.
  63. * <p>
  64. * If a name for the desired display language is not available, the
  65. * method may fall back to some other language.
  66. *
  67. * @param inputLocale the locale for which text input is supported, or null
  68. * @param displayLanguage the language in which the name will be displayed
  69. */
  70. String getInputMethodDisplayName(Locale inputLocale, Locale displayLanguage);
  71. /**
  72. * Returns an icon for the corresponding input method.
  73. * The icon may be used by a user interface for selecting input methods.
  74. * <p>
  75. * The inputLocale parameter specifies the locale for which text
  76. * is input.
  77. * This parameter can only take values obtained from this descriptor's
  78. * {@link #getAvailableLocales} method or null. If it is null, an
  79. * input locale independent icon for the input method should be
  80. * returned.
  81. * <p>
  82. * The icon's size should be 16×16 pixels.
  83. *
  84. * @param inputLocale the locale for which text input is supported, or null
  85. * @return an icon for the corresponding input method, or null
  86. */
  87. Image getInputMethodIcon(Locale inputLocale);
  88. /**
  89. * Creates a new instance of the corresponding input method.
  90. *
  91. * @return a new instance of the corresponding input method
  92. * @exception Exception any exception that may occur while creating the
  93. * input method instance
  94. */
  95. InputMethod createInputMethod() throws Exception;
  96. }