CVSROOT: /cvsroot/classpath
Module name: classpath
Changes by: Lillian Angel <langel> 06/06/20 18:24:14
Modified files:
. : ChangeLog
javax/swing/text: JTextComponent.java
Log message:
2006-06-20 Lillian Angel <[EMAIL PROTECTED]>
* javax/swing/text/JTextComponent.java
(AccessibleJTextComponent): Rewrote all javadocs
for this inner class.
CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/classpath/ChangeLog?cvsroot=classpath&r1=1.7884&r2=1.7885
http://cvs.savannah.gnu.org/viewcvs/classpath/javax/swing/text/JTextComponent.java?cvsroot=classpath&r1=1.58&r2=1.59
Patches:
Index: ChangeLog
===================================================================
RCS file: /cvsroot/classpath/classpath/ChangeLog,v
retrieving revision 1.7884
retrieving revision 1.7885
diff -u -b -r1.7884 -r1.7885
--- ChangeLog 20 Jun 2006 16:24:21 -0000 1.7884
+++ ChangeLog 20 Jun 2006 18:24:13 -0000 1.7885
@@ -1,3 +1,9 @@
+2006-06-20 Lillian Angel <[EMAIL PROTECTED]>
+
+ * javax/swing/text/JTextComponent.java
+ (AccessibleJTextComponent): Rewrote all javadocs
+ for this inner class.
+
2006-06-20 Francis Kung <[EMAIL PROTECTED]>
* examples/gnu/classpath/examples/java2d/J2dBenchmark.java:
Index: javax/swing/text/JTextComponent.java
===================================================================
RCS file: /cvsroot/classpath/classpath/javax/swing/text/JTextComponent.java,v
retrieving revision 1.58
retrieving revision 1.59
diff -u -b -r1.58 -r1.59
--- javax/swing/text/JTextComponent.java 15 May 2006 13:01:03 -0000
1.58
+++ javax/swing/text/JTextComponent.java 20 Jun 2006 18:24:14 -0000
1.59
@@ -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).
+ * Retrieve the current caret position. The index of the first
+ * caret position is 0.
*
- * @return offset of caret
+ * @return caret position
*/
public int getCaretPosition()
{
@@ -130,9 +133,10 @@
}
/**
- * Returns the portion of the text that is selected.
+ * Retrieve the current text selection. If no text is selected
+ * this method returns null.
*
- * @return null if no text is selected.
+ * @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.
+ * 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 index of the start of the text >= 0.
+ * @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.
+ * 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 index of the end of the text >= 0.
+ * @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.
+ * Handle a change in the caret position and fire any applicable
+ * property change events.
*
- * @param e - caret event
+ * @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,7 +216,8 @@
}
/**
- * Returns the AccessibleEditableText interface for this text component.
+ * Retrieve an AccessibleEditableText object that controls this
+ * text component.
*
* @return this
*/
@@ -220,10 +227,8 @@
}
/**
- * 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.
+ * Handle a text insertion event and fire an
+ * AccessibleContext.ACCESSIBLE_TEXT_PROPERTY property change
+ * event.
*
- * @param e - document 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.
+ * Handle a text removal event and fire an
+ * AccessibleContext.ACCESSIBLE_TEXT_PROPERTY property change
+ * event.
*
- * @param e - document 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.
+ * Handle a text change event and fire an
+ * AccessibleContext.ACCESSIBLE_TEXT_PROPERTY property change
+ * event.
*
- * @param e - document 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 - index of the character
*
- * @param index the 0-based character index
* @return the character's attributes
*/
public AttributeSet getCharacterAttribute(int index)
@@ -326,12 +334,13 @@
}
/**
- * Returns the section of text at the index, or null if the index or part
- * is invalid.
+ * 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 the 0-based character index
- * @return the selection of text at that index, or null
+ * @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
@@ -340,12 +349,13 @@
}
/**
- * Returns the section of text after the index, or null if the index or
part
- * is invalid.
+ * 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
*
- * @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
+ * @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.
+ * 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
*
- * @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
+ * @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 describe, 0-based
- * @return description of the action
+ * @param i - the action to get the description for
+ *
+ * @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
*
- * @param i the action to perform, 0-based
- * @return true if the action was performed
+ * @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
