I rewrote the docs for this inner class. 2006-06-20 Lillian Angel <[EMAIL PROTECTED]>
* javax/swing/text/JTextComponent.java (AccessibleJTextComponent): Rewrote all javadocs for this inner class.
Index: javax/swing/text/JTextComponent.java =================================================================== RCS file: /cvsroot/classpath/classpath/javax/swing/text/JTextComponent.java,v retrieving revision 1.58 diff -u -r1.58 JTextComponent.java --- javax/swing/text/JTextComponent.java 15 May 2006 13:01:03 -0000 1.58 +++ javax/swing/text/JTextComponent.java 20 Jun 2006 18:22:57 -0000 @@ -90,9 +90,10 @@ implements Scrollable, Accessible { /** - * This class implements accessibility support for the JTextComponent class. - * It provides an implementation of the Java Accessibility API appropriate - * to menu user-interface elements. + * AccessibleJTextComponent implements accessibility hooks for + * JTextComponent. It allows an accessibility driver to read and + * manipulate the text component's contents as well as update UI + * elements such as the caret. */ public class AccessibleJTextComponent extends AccessibleJComponent implements AccessibleText, CaretListener, DocumentListener, AccessibleAction, @@ -100,15 +101,18 @@ { private static final long serialVersionUID = 7664188944091413696L; - /** The caret's offset. */ + /** + * The caret's offset. + */ int dot = 0; - - /** The current JTextComponent. */ + + /** + * The current JTextComponent. + */ JTextComponent textComp = JTextComponent.this; - + /** - * Constructs an AccessibleJTextComponent. - * Adds a listener to track caret change. + * Construct an AccessibleJTextComponent. */ public AccessibleJTextComponent() { @@ -117,11 +121,10 @@ } /** - * Returns the zero-based offset of the caret. Note: The character - * to the right of the caret will have the same index value as the - * offset (the caret is between two characters). - * - * @return offset of caret + * Retrieve the current caret position. The index of the first + * caret position is 0. + * + * @return caret position */ public int getCaretPosition() { @@ -130,9 +133,10 @@ } /** - * Returns the portion of the text that is selected. - * - * @return null if no text is selected. + * Retrieve the current text selection. If no text is selected + * this method returns null. + * + * @return the currently selected text or null */ public String getSelectedText() { @@ -140,11 +144,14 @@ } /** - * Returns the start offset within the selected text. If there is no - * selection, but there is a caret, the start and end offsets will be - * the same. Return 0 if the text is empty, or the caret position if no selection. - * - * @return index of the start of the text >= 0. + * Retrieve the index of the first character in the current text + * selection. If there is no text in the text component, this + * method returns 0. If there is text in the text component, but + * there is no selection, this method returns the current caret + * position. + * + * @return the index of the first character in the selection, the + * current caret position or 0 */ public int getSelectionStart() { @@ -154,12 +161,14 @@ } /** - * Returns the end offset within the selected text. If there is no - * selection, but there is a caret, the start and end offsets will - * be the same. Return 0 if the text is empty, or the caret position - * if no selection. - * - * @return index of the end of the text >= 0. + * Retrieve the index of the last character in the current text + * selection. If there is no text in the text component, this + * method returns 0. If there is text in the text component, but + * there is no selection, this method returns the current caret + * position. + * + * @return the index of the last character in the selection, the + * current caret position or 0 */ public int getSelectionEnd() { @@ -169,13 +178,10 @@ } /** - * Handles caret updates (fire appropriate property change event, which are - * AccessibleContext.ACCESSIBLE_CARET_PROPERTY and - * AccessibleContext.ACCESSIBLE_SELECTION_PROPERTY). This keeps track of - * the dot position internally. When the caret moves, the internal position - * is updated after firing the event. - * - * @param e - caret event + * Handle a change in the caret position and fire any applicable + * property change events. + * + * @param e - the caret update event */ public void caretUpdate(CaretEvent e) throws NotImplementedException @@ -185,7 +191,7 @@ } /** - * Returns the accessible state set of this component. + * Retreive the accessible state set of this component. * * @return the accessible state set of this component */ @@ -198,7 +204,7 @@ } /** - * Returns the accessible role of this component. + * Retrieve the accessible role of this component. * * @return the accessible role of this component * @@ -210,20 +216,19 @@ } /** - * Returns the AccessibleEditableText interface for this text component. - * + * Retrieve an AccessibleEditableText object that controls this + * text component. + * * @return this */ public AccessibleEditableText getAccessibleEditableText() { return this; } - + /** - * Get the AccessibleText associated with this object. In the implementation - * of the Java Accessibility API for this class, return this object, - * which is responsible for implementing the AccessibleText interface on - * behalf of itself. + * Retrieve an AccessibleText object that controls this text + * component. * * @return this * @@ -235,10 +240,11 @@ } /** - * Insert update. Fire appropriate property change event which - * is AccessibleContext.ACCESSIBLE_TEXT_PROPERTY. - * - * @param e - document event + * Handle a text insertion event and fire an + * AccessibleContext.ACCESSIBLE_TEXT_PROPERTY property change + * event. + * + * @param e - the insertion event */ public void insertUpdate(DocumentEvent e) throws NotImplementedException @@ -247,10 +253,11 @@ } /** - * Remove update. Fire appropriate property change event which - * is AccessibleContext.ACCESSIBLE_TEXT_PROPERTY. - * - * @param e - document event + * Handle a text removal event and fire an + * AccessibleContext.ACCESSIBLE_TEXT_PROPERTY property change + * event. + * + * @param e - the removal event */ public void removeUpdate(DocumentEvent e) throws NotImplementedException @@ -259,10 +266,11 @@ } /** - * Changed update. Fire appropriate property change event which - * is AccessibleContext.ACCESSIBLE_TEXT_PROPERTY. - * - * @param e - document event + * Handle a text change event and fire an + * AccessibleContext.ACCESSIBLE_TEXT_PROPERTY property change + * event. + * + * @param e - text change event */ public void changedUpdate(DocumentEvent e) throws NotImplementedException @@ -271,11 +279,13 @@ } /** - * Given a point in the coordinate system of this object, return the - * 0-based index of the character at that point, or -1 if there is none. + * Get the index of the character at the given point, in component + * pixel co-ordinates. If the point argument is invalid this + * method returns -1. * - * @param p the point to look at - * @return the character index, or -1 + * @param p - a point in component pixel co-ordinates + * + * @return a character index, or -1 */ public int getIndexAtPoint(Point p) throws NotImplementedException @@ -284,17 +294,14 @@ } /** - * Determines the bounding box of the indexed character. Returns an empty - * rectangle if the index is out of bounds. The bounds are returned in local coordinates. - * If the index is invalid a null rectangle is returned. The screen coordinates returned are - * "unscrolled coordinates" if the JTextComponent is contained in a JScrollPane in which - * case the resulting rectangle should be composed with the parent coordinates. - * Note: the JTextComponent must have a valid size (e.g. have been added to a parent - * container whose ancestor container is a valid top-level window) for this method to - * be able to return a meaningful (non-null) value. + * Calculate the bounding box of the character at the given index. + * The returned x and y co-ordinates are relative to this text + * component's top-left corner. If the index is invalid this + * method returns null. + * + * @param index - the character index * - * @param index the 0-based character index - * @return the bounding box, may be empty or null. + * @return a character's bounding box, or null */ public Rectangle getCharacterBounds(int index) throws NotImplementedException @@ -303,9 +310,9 @@ } /** - * Return the number of characters. + * Return the length of the text in this text component. * - * @return the character count + * @return a character length */ public int getCharCount() { @@ -313,10 +320,11 @@ } /** - * Returns the attributes of a character at an index, or null if the index - * is out of bounds. + * Gets the character attributes of the character at index. If + * the index is out of bounds, null is returned. * - * @param index the 0-based character index + * @param index - index of the character + * * @return the character's attributes */ public AttributeSet getCharacterAttribute(int index) @@ -326,26 +334,28 @@ } /** - * Returns the section of text at the index, or null if the index or part - * is invalid. - * - * @param part [EMAIL PROTECTED] #CHARACTER}, [EMAIL PROTECTED] #WORD}, or [EMAIL PROTECTED] #SENTENCE} - * @param index the 0-based character index - * @return the selection of text at that index, or null + * Gets the text located at index. null is returned if the index + * or part is invalid. + * + * @param part - [EMAIL PROTECTED] #CHARACTER}, [EMAIL PROTECTED] #WORD}, or [EMAIL PROTECTED] #SENTENCE} + * @param index - index of the part + * + * @return the part of text at that index, or null */ public String getAtIndex(int part, int index) throws NotImplementedException { return null; // TODO } - + /** - * Returns the section of text after the index, or null if the index or part - * is invalid. - * - * @param part [EMAIL PROTECTED] #CHARACTER}, [EMAIL PROTECTED] #WORD}, or [EMAIL PROTECTED] #SENTENCE} - * @param index the 0-based character index - * @return the selection of text after that index, or null + * Gets the text located after index. null is returned if the index + * or part is invalid. + * + * @param part - [EMAIL PROTECTED] #CHARACTER}, [EMAIL PROTECTED] #WORD}, or [EMAIL PROTECTED] #SENTENCE} + * @param index - index after the part + * + * @return the part of text after that index, or null */ public String getAfterIndex(int part, int index) throws NotImplementedException @@ -354,12 +364,13 @@ } /** - * Returns the section of text before the index, or null if the index or part - * is invalid. - * - * @param part [EMAIL PROTECTED] #CHARACTER}, [EMAIL PROTECTED] #WORD}, or [EMAIL PROTECTED] #SENTENCE} - * @param index the 0-based character index - * @return the selection of text before that index, or null + * Gets the text located before index. null is returned if the index + * or part is invalid. + * + * @param part - [EMAIL PROTECTED] #CHARACTER}, [EMAIL PROTECTED] #WORD}, or [EMAIL PROTECTED] #SENTENCE} + * @param index - index before the part + * + * @return the part of text before that index, or null */ public String getBeforeIndex(int part, int index) throws NotImplementedException @@ -368,10 +379,10 @@ } /** - * Get the number possible actions for this object, with the zeroth - * representing the default action. + * Returns the number of actions for this object. The zero-th + * object represents the default action. * - * @return the 0-based number of actions + * @return the number of actions (0-based). */ public int getAccessibleActionCount() throws NotImplementedException @@ -380,11 +391,12 @@ } /** - * Get a description for the specified action. Returns null if out of - * bounds. + * Returns the description of the i-th action. Null is returned if + * i is out of bounds. + * + * @param i - the action to get the description for * - * @param i the action to describe, 0-based - * @return description of the action + * @return description of the i-th action */ public String getAccessibleActionDescription(int i) throws NotImplementedException @@ -394,10 +406,12 @@ } /** - * Perform the specified action. Does nothing if out of bounds. + * Performs the i-th action. Nothing happens if i is + * out of bounds. * - * @param i the action to perform, 0-based - * @return true if the action was performed + * @param i - the action to perform + * + * @return true if the action was performed successfully */ public boolean doAccessibleAction(int i) throws NotImplementedException @@ -406,9 +420,9 @@ } /** - * Set the text contents to the given string. + * Sets the text contents. * - * @param s the new text + * @param s - the new text contents. */ public void setTextContents(String s) throws NotImplementedException @@ -417,10 +431,10 @@ } /** - * Inserts the given string at the specified location. + * Inserts the text at the given index. * - * @param index the index for insertion - * @param s the new text + * @param index - the index to insert the new text at. + * @param s - the new text */ public void insertTextAtIndex(int index, String s) throws NotImplementedException @@ -429,10 +443,10 @@ } /** - * Return the text between two points. + * Gets the text between two indexes. * - * @param start the start position, inclusive - * @param end the end position, exclusive + * @param start - the starting index (inclusive) + * @param end - the ending index (exclusive) */ public String getTextRange(int start, int end) { @@ -447,10 +461,10 @@ } /** - * Delete the text between two points. + * Deletes the text between two indexes. * - * @param start the start position, inclusive - * @param end the end position, exclusive + * @param start - the starting index (inclusive) + * @param end - the ending index (exclusive) */ public void delete(int start, int end) { @@ -458,10 +472,11 @@ } /** - * Cut the text between two points to the system clipboard. + * Cuts the text between two indexes. The text is put + * into the system clipboard. * - * @param start the start position, inclusive - * @param end the end position, exclusive + * @param start - the starting index (inclusive) + * @param end - the ending index (exclusive) */ public void cut(int start, int end) { @@ -470,9 +485,9 @@ } /** - * Paste the text from the system clipboard at the given index. + * Pastes the text from the system clipboard to the given index. * - * @param start the start position + * @param start - the starting index */ public void paste(int start) { @@ -481,11 +496,12 @@ } /** - * Replace the text between two points with the given string. + * Replaces the text between two indexes with the given text. + * * - * @param start the start position, inclusive - * @param end the end position, exclusive - * @param s the string to paste + * @param start - the starting index (inclusive) + * @param end - the ending index (exclusive) + * @param s - the text to paste */ public void replaceText(int start, int end, String s) { @@ -494,10 +510,10 @@ } /** - * Select the text between two points. + * Selects the text between two indexes. * - * @param start the start position, inclusive - * @param end the end position, exclusive + * @param start - the starting index (inclusive) + * @param end - the ending index (exclusive) */ public void selectText(int start, int end) { @@ -505,11 +521,11 @@ } /** - * Set the attributes of text between two points. + * Sets the attributes of all the text between two indexes. * - * @param start the start position, inclusive - * @param end the end position, exclusive - * @param s the new attribute set for the range + * @param start - the starting index (inclusive) + * @param end - the ending index (exclusive) + * @param s - the new attribute set for the text in the range */ public void setAttributes(int start, int end, AttributeSet s) throws NotImplementedException