1. /*
  2. * @(#)JPasswordField.java 1.42 00/04/06
  3. *
  4. * Copyright 1997-2000 Sun Microsystems, Inc. All Rights Reserved.
  5. *
  6. * This software is the proprietary information of Sun Microsystems, Inc.
  7. * Use is subject to license terms.
  8. *
  9. */
  10. package javax.swing;
  11. import javax.swing.text.*;
  12. import javax.swing.plaf.*;
  13. import javax.accessibility.*;
  14. import java.io.ObjectOutputStream;
  15. import java.io.ObjectInputStream;
  16. import java.io.IOException;
  17. /**
  18. * JPasswordField is a lightweight component that allows the editing
  19. * of a single line of text where the view indicates something was
  20. * typed, but does not show the original characters.
  21. * You can find further information and examples in
  22. * <a href="http://java.sun.com/docs/books/tutorial/uiswing/components/textfield.html">How to Use Text Fields</a>,
  23. * a section in <em>The Java Tutorial.</em>
  24. * <p>
  25. * JPasswordField is intended
  26. * to be source-compatible with java.awt.TextField used with echoChar
  27. * set. It is provided seperately to make it easier to safely change
  28. * the ui for the JTextField without affecting password entries.
  29. * <p>
  30. * For the keyboard keys used by this component in the standard Look and
  31. * Feel (L&F) renditions, see the
  32. * <a href="doc-files/Key-Index.html#JPasswordField">JPasswordField</a>
  33. * key assignments.
  34. * <p>
  35. * <strong>Warning:</strong>
  36. * Serialized objects of this class will not be compatible with
  37. * future Swing releases. The current serialization support is appropriate
  38. * for short term storage or RMI between applications running the same
  39. * version of Swing. A future release of Swing will provide support for
  40. * long term persistence.
  41. *
  42. * @beaninfo
  43. * attribute: isContainer false
  44. * description: Allows the editing of a line of text but doesn't show the characters.
  45. *
  46. * @author Timothy Prinzing
  47. * @version 1.42 04/06/00
  48. */
  49. public class JPasswordField extends JTextField {
  50. /**
  51. * Constructs a new JPasswordField, with a default document, null starting
  52. * text string, and 0 column width.
  53. */
  54. public JPasswordField() {
  55. this(null,null,0);
  56. }
  57. /**
  58. * Constructs a new JPasswordField initialized with the specified text.
  59. * The document model is set to the default, and the number of columns to 0.
  60. *
  61. * @param text the text to be displayed, null if none
  62. */
  63. public JPasswordField(String text) {
  64. this(null, text, 0);
  65. }
  66. /**
  67. * Constructs a new empty JPasswordField with the specified
  68. * number of columns. A default model is created, and the initial string
  69. * is set to null.
  70. *
  71. * @param columns the number of columns >= 0
  72. */
  73. public JPasswordField(int columns) {
  74. this(null, null, columns);
  75. }
  76. /**
  77. * Constructs a new JPasswordField initialized with the specified text
  78. * and columns. The document model is set to the default.
  79. *
  80. * @param text the text to be displayed, null if none
  81. * @param columns the number of columns >= 0
  82. */
  83. public JPasswordField(String text, int columns) {
  84. this(null, text, columns);
  85. }
  86. /**
  87. * Constructs a new JPasswordField that uses the given text storage
  88. * model and the given number of columns. This is the constructor
  89. * through which the other constructors feed. The echo character is
  90. * set to '*'. If the document model is null, a default one will be
  91. * created.
  92. *
  93. * @param doc the text storage to use
  94. * @param txt the text to be displayed, null if none
  95. * @param columns the number of columns to use to calculate
  96. * the preferred width >= 0. If columns is set to zero, the
  97. * preferred width will be whatever naturally results from
  98. * the component implementation.
  99. */
  100. public JPasswordField(Document doc, String txt, int columns) {
  101. super(doc, txt, columns);
  102. echoChar = '*';
  103. }
  104. /**
  105. * Returns the name of the L&F class that renders this component.
  106. *
  107. * @return "PasswordFieldUI"
  108. * @see JComponent#getUIClassID
  109. * @see UIDefaults#getUI
  110. */
  111. public String getUIClassID() {
  112. return uiClassID;
  113. }
  114. /**
  115. * Returns the character to be used for echoing. The default is '*'.
  116. *
  117. * @return the echo character, 0 if unset
  118. * @see #setEchoChar
  119. * @see #echoCharIsSet
  120. */
  121. public char getEchoChar() {
  122. return echoChar;
  123. }
  124. /**
  125. * Sets the echo character for this JPasswordField. Note
  126. * that this is largely a suggestion to the view as the
  127. * view that gets installed can use whatever graphic techniques
  128. * it desires to represent the field. Setting a value of 0 unsets
  129. * the echo character.
  130. *
  131. * @param c the echo character to display
  132. * @see #echoCharIsSet
  133. * @see #getEchoChar
  134. * @beaninfo
  135. * description: character to display in place of the real characters
  136. */
  137. public void setEchoChar(char c) {
  138. echoChar = c;
  139. }
  140. /**
  141. * Returns true if this JPasswordField has a character set for
  142. * echoing. A character is considered to be set if the echo character
  143. * is not 0.
  144. *
  145. * @return true if a character is set for echoing
  146. * @see #setEchoChar
  147. * @see #getEchoChar
  148. */
  149. public boolean echoCharIsSet() {
  150. return echoChar != 0;
  151. }
  152. // --- JTextComponent methods ----------------------------------
  153. /**
  154. * Normally transfers the currently selected range in the associated
  155. * text model to the system clipboard, removing the contents
  156. * from the model. This is not a good thing for a password field
  157. * and is reimplemented to simply beep.
  158. */
  159. public void cut() {
  160. getToolkit().beep();
  161. }
  162. /**
  163. * Normally transfers the currently selected range in the associated
  164. * text model to the system clipboard, leaving the contents
  165. * in the text model. This is not a good thing for a password field
  166. * and is reimplemented to simply beep.
  167. */
  168. public void copy() {
  169. getToolkit().beep();
  170. }
  171. /**
  172. * Returns the text contained in this TextComponent. If the underlying
  173. * document is null, will give a NullPointerException.
  174. * <p>
  175. * For security reasons, this method is deprecated. Use the
  176. * getPassword method instead.
  177. * @deprecated As of Java 2 platform v1.2,
  178. * replaced by <code>getPassword()</code>.
  179. * @return the text
  180. */
  181. public String getText() {
  182. return super.getText();
  183. }
  184. /**
  185. * Fetches a portion of the text represented by the
  186. * component. Returns an empty string if length is 0.
  187. * <p>
  188. * For security reasons, this method is deprecated. Use the
  189. * getPassword method instead.
  190. * @deprecated As of Java 2 platform v1.2,
  191. * replaced by <code>getPassword()</code>.
  192. * @param offs the offset >= 0
  193. * @param len the length >= 0
  194. * @return the text
  195. * @exception BadLocationException if the offset or length are invalid
  196. */
  197. public String getText(int offs, int len) throws BadLocationException {
  198. return super.getText(offs, len);
  199. }
  200. /**
  201. * Returns the text contained in this TextComponent. If the underlying
  202. * document is null, will give a NullPointerException. For stronger
  203. * security, it is recommended that the returned character array be
  204. * cleared after use by setting each character to zero.
  205. *
  206. * @return the text
  207. */
  208. public char[] getPassword() {
  209. Document doc = getDocument();
  210. Segment txt = new Segment();
  211. try {
  212. doc.getText(0, doc.getLength(), txt); // use the non-String API
  213. } catch (BadLocationException e) {
  214. return null;
  215. }
  216. char[] retValue = new char[txt.count];
  217. System.arraycopy(txt.array, txt.offset, retValue, 0, txt.count);
  218. return retValue;
  219. }
  220. /**
  221. * See readObject() and writeObject() in JComponent for more
  222. * information about serialization in Swing.
  223. */
  224. private void writeObject(ObjectOutputStream s) throws IOException {
  225. s.defaultWriteObject();
  226. if ((ui != null) && (getUIClassID().equals(uiClassID))) {
  227. ui.installUI(this);
  228. }
  229. }
  230. // --- variables -----------------------------------------------
  231. /**
  232. * @see #getUIClassID
  233. * @see #readObject
  234. */
  235. private static final String uiClassID = "PasswordFieldUI";
  236. private char echoChar;
  237. /**
  238. * Returns a string representation of this JPasswordField. This method
  239. * is intended to be used only for debugging purposes, and the
  240. * content and format of the returned string may vary between
  241. * implementations. The returned string may be empty but may not
  242. * be <code>null</code>.
  243. *
  244. * @return a string representation of this JPasswordField.
  245. */
  246. protected String paramString() {
  247. return super.paramString() +
  248. ",echoChar=" + echoChar;
  249. }
  250. /////////////////
  251. // Accessibility support
  252. ////////////////
  253. /**
  254. * Gets the AccessibleContext associated with this JPasswordField.
  255. * For password fields, the AccessibleContext takes the form of an
  256. * AccessibleJPasswordField.
  257. * A new AccessibleJPasswordField instance is created if necessary.
  258. *
  259. * @return an AccessibleJPasswordField that serves as the
  260. * AccessibleContext of this JPasswordField
  261. */
  262. public AccessibleContext getAccessibleContext() {
  263. if (accessibleContext == null) {
  264. accessibleContext = new AccessibleJPasswordField();
  265. }
  266. return accessibleContext;
  267. }
  268. /**
  269. * This class implements accessibility support for the
  270. * <code>JPasswordField</code> class. It provides an implementation of the
  271. * Java Accessibility API appropriate to password field user-interface
  272. * elements.
  273. * <p>
  274. * <strong>Warning:</strong>
  275. * Serialized objects of this class will not be compatible with
  276. * future Swing releases. The current serialization support is appropriate
  277. * for short term storage or RMI between applications running the same
  278. * version of Swing. A future release of Swing will provide support for
  279. * long term persistence.
  280. */
  281. protected class AccessibleJPasswordField extends AccessibleJTextField {
  282. /**
  283. * Gets the role of this object.
  284. *
  285. * @return an instance of AccessibleRole describing the role of the
  286. * object (AccessibleRole.PASSWORD_TEXT)
  287. * @see AccessibleRole
  288. */
  289. public AccessibleRole getAccessibleRole() {
  290. return AccessibleRole.PASSWORD_TEXT;
  291. }
  292. }
  293. }