8235818: Inline information from broken external links in java.desktop
Reviewed-by: prr
diff --git a/src/java.desktop/share/classes/javax/swing/Timer.java b/src/java.desktop/share/classes/javax/swing/Timer.java
index 12c8c81..ab87f75 100644
--- a/src/java.desktop/share/classes/javax/swing/Timer.java
+++ b/src/java.desktop/share/classes/javax/swing/Timer.java
@@ -124,13 +124,6 @@
* <a href="https://docs.oracle.com/javase/tutorial/uiswing/misc/timer.html"
* target = "_top">How to Use Timers</a>,
* a section in <em>The Java Tutorial.</em>
- * For more examples and help in choosing between
- * this <code>Timer</code> class and
- * <code>java.util.Timer</code>,
- * see
- * <a href="http://java.sun.com/products/jfc/tsc/articles/timer/"
- * target="_top">Using Timers in Swing Applications</a>,
- * an article in <em>The Swing Connection.</em>
* <p>
* <strong>Warning:</strong>
* Serialized objects of this class will not be compatible with
diff --git a/src/java.desktop/share/classes/javax/swing/text/Document.java b/src/java.desktop/share/classes/javax/swing/text/Document.java
index 037fae7..e0f4ac7 100644
--- a/src/java.desktop/share/classes/javax/swing/text/Document.java
+++ b/src/java.desktop/share/classes/javax/swing/text/Document.java
@@ -165,11 +165,182 @@
* <li>{@link #putProperty(java.lang.Object, java.lang.Object)}
* </ul>
*
- * <p>For more information on the <code>Document</code> class, see
- * <a href="http://www.oracle.com/technetwork/java/javase/tech/articles-jsp-139072.html">The Swing Connection</a>
- * and most particularly the article,
- * <a href="http://java.sun.com/products/jfc/tsc/articles/text/element_interface">
- * The Element Interface</a>.
+ * <p><b>Overview and Programming Tips</b>
+ * <p><u>{@link javax.swing.text.Element}</u> is an important interface used in constructing a Document.
+ * It has the power to describe various structural parts of a document,
+ * such as paragraphs, lines of text, or even (in HTML documents) items in lists.
+ * Conceptually, the Element interface captures some of the spirit of an SGML document.
+ * So if you know SGML, you may already have some understanding of Swing's Element interface.
+ * <p>In the Swing text API's document model, the interface Element defines a structural piece of a Document,
+ * like a paragraph, a line of text, or a list item in an HTML document.
+ * <p>Every Element is either a <i>branch</i> or a <i>leaf</i>. If an element is a branch,
+ * the <code>isLeaf()</code> method returns false. If an element is a a leaf, <code>isLeaf()</code> returns true.
+ * <p>Branches can have any number of children. Leaves do not have children.
+ * To determine how many children a branch has, you can call <code>getElementCount()</code>.
+ * To determine the parent of an Element, you can call <code>getParentElement()</code>.
+ * Root elements don't have parents, so calling <code>getParentElement()</code> on a root returns null.
+ * <p>An Element represents a specific region in a Document that begins with startOffset
+ * and ends just before endOffset.
+ * The start offset of a branch Element is usually the start offset of its first child.
+ * Similarly, the end offset of a branch Element is usually the end offset of its last child.
+ * <p>Every Element is associated with an AttributeSet that you can access by calling <code>getAttributes()</code>.
+ * In an Element, and AttributeSet is essentially a set of key/value pairs.
+ * These pairs are generally used for markup -- such as determining the Element's
+ * foreground color, font size, and so on. But it is up to the model, and the developer,
+ * to determine what is stored in the AttributeSet.
+ * <p>You can obtain the root Element (or Elements) of a Document by calling the
+ * methods <code>getDefaultRootElement()</code> and <code>getRootElements()</code>, which are defined in the Document interface.
+ * <p>The Document interface is responsible for translating a linear view of the
+ * characters into Element operations. It is up to each Document implementation
+ * to define what the Element structure is.
+ *
+ * <p><b>The PlainDocument class</b>
+ * <p>The <u>{@link javax.swing.text.PlainDocument}</u> class defines an Element
+ * structure in which the root node has a child node for each line of text in the model.
+ * <u>Figure 1</u> shows how two lines of text would be modeled by a PlainDocument
+ * <p style="text-align:center"><img src="doc-files/plain1.gif"
+ * alt="The preceding text describes this graphic.">
+ * <p><u>Figure 2</u> shows how how those same two lines of text might map to actual content:
+ * <p style="text-align:center"><img src="doc-files/plain2.gif"
+ * alt="The preceding text describes this graphic.">
+ *
+ * <p><b>Inserting text into a PlainDocument</b>
+ * <p>As just mentioned, a PlainDocument contains a root Element, which in turn
+ * contains an Element for each line of text.
+ * When text is inserted into a PlainDocument, it creates the Elements that
+ * are needed for an Element to exist for each newline.
+ * To illustrate, let's say you wanted to insert a newline at offset 2 in <u>Figure 2</u>, above.
+ * To accomplish this objective, you could use the Document method <code>insertString()</code>,
+ * using this syntax:
+ * <pre><code>document.insertString(2, "\n", null);</code></pre>
+ * <p>After invoking the <code>insertString()</code> method, the Element structure would look
+ * like the one shown in <u>Figure 3</u>.
+ * <p style="text-align:center"><img src="doc-files/plain3.gif"
+ * alt="The preceding text describes this graphic.">
+ * <p>As another example, let's say you wanted to insert the pattern "new\ntext\n"
+ * at offset 2 as shown previously in <u>Figure 2</u>. This operation would have the
+ * result shown in <u>Figure 4</u>.
+ * <p style="text-align:center"><img src="doc-files/plain4.gif"
+ * alt="The preceding text describes this graphic.">
+ * <p>In the preceding illustrations, the name of the line Elements is changed
+ * after the insertion to match the line numbers.
+ * But notice that when this is done, the AttributeSets remain the same.
+ * For example, in <u>Figure 2</u>, the AttributeSet of Line 2 matches that of the
+ * AttributeSet of Line 4 in <u>Figure 4</u>.
+ *
+ * <p><b>Removing text from a PlainDocument</b>
+ * <p>Removal of text results in a structure change if the deletion spans more than one line.
+ * Consider a deletion of seven characters starting at Offset 1 shown previously in <u>Figure 3</u>.
+ * In this case, the Element representing Line 2 is completely removed, as the
+ * region it represents is contained in the deleted region.
+ * The Elements representing Lines 1 and 3 are joined, as they are partially
+ * contained in the deleted region. Thus, we have the result:
+ * <p style="text-align:center"><img src="doc-files/plain5.gif"
+ * alt="The preceding text describes this graphic.">
+ *
+ * <p><b>The Default StyledDocument Class</b>
+ * <p>The <u>{@link javax.swing.text.DefaultStyledDocument}</u> class, used for styled text,
+ * contains another level of Elements.
+ * This extra level is needed so that each paragraph can contain different styles of text.
+ * In the two paragraphs shown in <u>Figure 6</u>, the first paragraph contains
+ * two styles and the second paragraph contains three styles.
+ * <p style="text-align:center"><img src="doc-files/plain6.gif"
+ * alt="The preceding text describes this graphic.">
+ * <p><u>Figure 7</u> shows how those same Elements might map to content.
+ * <p style="text-align:center"><img src="doc-files/plain7.gif"
+ * alt="The preceding text describes this graphic.">
+ *
+ * <p><b>Inserting text into a DefaultStyledDocument</b>
+ * <p>As previously mentioned, DefaultStyledDocument maintains an Element structure
+ * such that the root Element
+ * contains a child Element for each paragraph. In turn, each of these
+ * paragraph Elements contains an Element for each style of text in the paragraph.
+ * As an example, let's say you had a document containing one paragraph,
+ * and that this paragraph contained two styles, as shown in <u>Figure 8</u>.
+ * <p style="text-align:center"><img src="doc-files/plain8.gif"
+ * alt="The preceding text describes this graphic.">
+ * <p>If you then wanted to insert a newline at offset 2, you would again use the
+ * method <code>insertString()</code>, as follows:
+ *
+ * <pre><code> styledDocument.insertString(2, "\n",
+ styledDocument.getCharacterElement(0).getAttributes());</code></pre>
+
+ * <p>This operation would have the result shown in <u>Figure 9</u>.
+ * <p style="text-align:center"><img src="doc-files/plain9.gif"
+ * alt="The preceding text describes this graphic.">
+ * <p>It's important to note that the AttributeSet passed to <code>insertString()</code> matches
+ * that of the attributes of Style 1. If the AttributeSet passed to <code>insertString()</code>
+ * did not match, the result would be the situation shown in <u>Figure 10</u>.
+ * <p style="text-align:center"><img src="doc-files/plain10.gif"
+ * alt="The preceding text describes this graphic.">
+ * <p><b>Removing text from a DefaultStyledDocument</b>
+ * <p>Removing text from a DefaultStyledDocument is similar to removing text from
+ * a PlainDocument. The only difference is the extra level of Elements.
+ * Consider what would happen if you deleted two characters at Offset 1
+ * from Figure 10, above. Since the the second Element of Paragraph 1 is
+ * completely contained in the deleted region, it would be removed.
+ * Assuming the attributes of Paragraph 1's first child matched those of
+ * Paragraph2's first child, the results would be those shown in <u>Figure 11</u>.
+ * <p style="text-align:center"><img src="doc-files/plain11.gif"
+ * alt="The preceding text describes this graphic.">
+ * <p>If the attributes did not match, we would get the results shown in <u>Figure 12</u>.
+ * <p style="text-align:center"><img src="doc-files/plain12.gif"
+ * alt="The preceding text describes this graphic.">
+ *
+ * <p><b>The StyledDocument Class</b>
+ * <p>The <u>{@link javax.swing.text.StyledDocument}</u> class provides a method
+ * named <code>setCharacterAttributes()</code>, which allows you to set the attributes
+ * on the character Elements in a given range:
+
+ * <pre><code> public void setCharacterAttributes
+ * (int offset, int length, AttributeSet s, boolean replace);</code></pre>
+ *
+ * <p>Recall that in the diagrams shown in the previous section, all leaf Elements
+ * shown in the drawings were also character Elements.
+ * That means that the <code>setCharacterAttributes()</code> method could be used to set their attributes.
+ * <p>The <code>setCharacterAttributes()</code> method takes four arguments .
+ * The first and second arguments identify a region in the Document that is
+ * to be changed. The third argument specifies the new attributes
+ * (as an AttributeSet), and the fourth argument determines if the new attributes
+ * should be added to the existing attributes (a value of false) or
+ * if the character Element should replace its existing attributes
+ * with the new attributes (a value of true).
+ * <p>As an example, let's say you wanted to change the attributes of the
+ * first three characters in <u>Figure 9</u>, shown previously.
+ * The first two arguments passed to <code>setCharacterAttributes()</code> would be 0 and 3.
+ * The third argument would be the AttributeSet containing the new attributes.
+ * In the example we are considering, it doesn't matter what the fourth argument is.
+ * <p>As the start and end offsets of the changed region (0 and 3) fall on
+ * character Element boundaries, no structure change is needed.
+ * That is, only the attributes of the character Element style 1 will change.
+ * <p>Now let's look at an example that requires a structure change.
+ * Instead of changing the first three characters shown in <u>Figure 9</u>,
+ * let's change the first two characters.
+ * Because the end change offset (2) does not fall on a character Element boundary,
+ * the Element at offset 2 must be split in such a way
+ * that offset 2 is the boundary of two Elements.
+ * Invoking <code>setCharacterAttributes()</code> with a start offset of 0
+ * and length of 2 has the result shown earlier in <u>Figure 10</u>.
+ * <p><b>Changing Paragraph Attributes in a StyledDocument</b>
+ * <p>The StyledDocument class provides a method named <code>setParagraphAttributes()</code>,
+ * which can be used to change the attributes of a paragraph Element:
+
+ * <pre><code> public void setParagraphAttributes
+ * (int offset, int length, AttributeSet s, boolean replace);</code></pre>
+ *
+ * <p>This method is similar to <code>setCharacterAttributes()</code>,
+ * but it allows you to change the attributes of paragraph Elements.
+ * It is up to the implementation of a StyledDocument to define which Elements
+ * are paragraphs. DefaultStyledDocument interprets paragraph Elements
+ * to be the parent Element of the character Element.
+ * Invoking this method does not result in a structure change;
+ * only the attributes of the paragraph Element change.
+ *
+ * <p>It is recommended to look into {@link javax.swing.text.EditorKit} and
+ * {@link javax.swing.text.View}.
+ * View is responsible for rendering a particular Element, and
+ * EditorKit is responsible for a ViewFactory that is able to decide what
+ * View should be created based on an Element.
*
* @author Timothy Prinzing
*
diff --git a/src/java.desktop/share/classes/javax/swing/text/doc-files/plain1.gif b/src/java.desktop/share/classes/javax/swing/text/doc-files/plain1.gif
new file mode 100644
index 0000000..7fe1d04
--- /dev/null
+++ b/src/java.desktop/share/classes/javax/swing/text/doc-files/plain1.gif
Binary files differ
diff --git a/src/java.desktop/share/classes/javax/swing/text/doc-files/plain10.gif b/src/java.desktop/share/classes/javax/swing/text/doc-files/plain10.gif
new file mode 100644
index 0000000..71f6b1e
--- /dev/null
+++ b/src/java.desktop/share/classes/javax/swing/text/doc-files/plain10.gif
Binary files differ
diff --git a/src/java.desktop/share/classes/javax/swing/text/doc-files/plain11.gif b/src/java.desktop/share/classes/javax/swing/text/doc-files/plain11.gif
new file mode 100644
index 0000000..9d660f0
--- /dev/null
+++ b/src/java.desktop/share/classes/javax/swing/text/doc-files/plain11.gif
Binary files differ
diff --git a/src/java.desktop/share/classes/javax/swing/text/doc-files/plain12.gif b/src/java.desktop/share/classes/javax/swing/text/doc-files/plain12.gif
new file mode 100644
index 0000000..7775d13
--- /dev/null
+++ b/src/java.desktop/share/classes/javax/swing/text/doc-files/plain12.gif
Binary files differ
diff --git a/src/java.desktop/share/classes/javax/swing/text/doc-files/plain2.gif b/src/java.desktop/share/classes/javax/swing/text/doc-files/plain2.gif
new file mode 100644
index 0000000..7d4d4c5
--- /dev/null
+++ b/src/java.desktop/share/classes/javax/swing/text/doc-files/plain2.gif
Binary files differ
diff --git a/src/java.desktop/share/classes/javax/swing/text/doc-files/plain3.gif b/src/java.desktop/share/classes/javax/swing/text/doc-files/plain3.gif
new file mode 100644
index 0000000..a86c89d
--- /dev/null
+++ b/src/java.desktop/share/classes/javax/swing/text/doc-files/plain3.gif
Binary files differ
diff --git a/src/java.desktop/share/classes/javax/swing/text/doc-files/plain4.gif b/src/java.desktop/share/classes/javax/swing/text/doc-files/plain4.gif
new file mode 100644
index 0000000..78da206
--- /dev/null
+++ b/src/java.desktop/share/classes/javax/swing/text/doc-files/plain4.gif
Binary files differ
diff --git a/src/java.desktop/share/classes/javax/swing/text/doc-files/plain5.gif b/src/java.desktop/share/classes/javax/swing/text/doc-files/plain5.gif
new file mode 100644
index 0000000..7181ad0
--- /dev/null
+++ b/src/java.desktop/share/classes/javax/swing/text/doc-files/plain5.gif
Binary files differ
diff --git a/src/java.desktop/share/classes/javax/swing/text/doc-files/plain6.gif b/src/java.desktop/share/classes/javax/swing/text/doc-files/plain6.gif
new file mode 100644
index 0000000..d349175
--- /dev/null
+++ b/src/java.desktop/share/classes/javax/swing/text/doc-files/plain6.gif
Binary files differ
diff --git a/src/java.desktop/share/classes/javax/swing/text/doc-files/plain7.gif b/src/java.desktop/share/classes/javax/swing/text/doc-files/plain7.gif
new file mode 100644
index 0000000..882f239
--- /dev/null
+++ b/src/java.desktop/share/classes/javax/swing/text/doc-files/plain7.gif
Binary files differ
diff --git a/src/java.desktop/share/classes/javax/swing/text/doc-files/plain8.gif b/src/java.desktop/share/classes/javax/swing/text/doc-files/plain8.gif
new file mode 100644
index 0000000..f21cd4d
--- /dev/null
+++ b/src/java.desktop/share/classes/javax/swing/text/doc-files/plain8.gif
Binary files differ
diff --git a/src/java.desktop/share/classes/javax/swing/text/doc-files/plain9.gif b/src/java.desktop/share/classes/javax/swing/text/doc-files/plain9.gif
new file mode 100644
index 0000000..5a955ba
--- /dev/null
+++ b/src/java.desktop/share/classes/javax/swing/text/doc-files/plain9.gif
Binary files differ
