1 /*
2 * Copyright (c) 1997, 2014, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
982
983 /**
984 * Replaces the children of the given element with the contents
985 * specified as an HTML string.
986 *
987 * <p>This will be seen as at least two events, n inserts followed by
988 * a remove.</p>
989 *
990 * <p>Consider the following structure (the <code>elem</code>
991 * parameter is <b>in bold</b>).</p>
992 *
993 * <pre>
994 * <body>
995 * |
996 * <b><div></b>
997 * / \
998 * <p> <p>
999 * </pre>
1000 *
1001 * <p>Invoking <code>setInnerHTML(elem, "<ul><li>")</code>
1002 * results in the following structure (new elements are <font
1003 * style="color: red;">in red</font>).</p>
1004 *
1005 * <pre>
1006 * <body>
1007 * |
1008 * <b><div></b>
1009 * \
1010 * <font style="color: red;"><ul></font>
1011 * \
1012 * <font style="color: red;"><li></font>
1013 * </pre>
1014 *
1015 * <p>Parameter <code>elem</code> must not be a leaf element,
1016 * otherwise an <code>IllegalArgumentException</code> is thrown.
1017 * If either <code>elem</code> or <code>htmlText</code> parameter
1018 * is <code>null</code>, no changes are made to the document.</p>
1019 *
1020 * <p>For this to work correctly, the document must have an
1021 * <code>HTMLEditorKit.Parser</code> set. This will be the case
1022 * if the document was created from an HTMLEditorKit via the
1023 * <code>createDefaultDocument</code> method.</p>
1024 *
1025 * @param elem the branch element whose children will be replaced
1026 * @param htmlText the string to be parsed and assigned to <code>elem</code>
1027 * @throws IllegalArgumentException if <code>elem</code> is a leaf
1028 * @throws IllegalStateException if an <code>HTMLEditorKit.Parser</code>
1029 * has not been defined
1030 * @throws BadLocationException if replacement is impossible because of
1031 * a structural issue
1032 * @throws IOException if an I/O exception occurs
1066 *
1067 * <p>If you try to replace the element at length you will most
1068 * likely end up with two elements, eg
1069 * <code>setOuterHTML(getCharacterElement (getLength()),
1070 * "blah")</code> will result in two leaf elements at the end, one
1071 * representing 'blah', and the other representing the end
1072 * element.</p>
1073 *
1074 * <p>Consider the following structure (the <code>elem</code>
1075 * parameter is <b>in bold</b>).</p>
1076 *
1077 * <pre>
1078 * <body>
1079 * |
1080 * <b><div></b>
1081 * / \
1082 * <p> <p>
1083 * </pre>
1084 *
1085 * <p>Invoking <code>setOuterHTML(elem, "<ul><li>")</code>
1086 * results in the following structure (new elements are <font
1087 * style="color: red;">in red</font>).</p>
1088 *
1089 * <pre>
1090 * <body>
1091 * |
1092 * <font style="color: red;"><ul></font>
1093 * \
1094 * <font style="color: red;"><li></font>
1095 * </pre>
1096 *
1097 * <p>If either <code>elem</code> or <code>htmlText</code>
1098 * parameter is <code>null</code>, no changes are made to the
1099 * document.</p>
1100 *
1101 * <p>For this to work correctly, the document must have an
1102 * HTMLEditorKit.Parser set. This will be the case if the document
1103 * was created from an HTMLEditorKit via the
1104 * <code>createDefaultDocument</code> method.</p>
1105 *
1106 * @param elem the element to replace
1107 * @param htmlText the string to be parsed and inserted in place of <code>elem</code>
1108 * @throws IllegalStateException if an HTMLEditorKit.Parser has not
1109 * been set
1110 * @throws BadLocationException if replacement is impossible because of
1111 * a structural issue
1112 * @throws IOException if an I/O exception occurs
1113 * @since 1.3
1114 */
1140 }
1141 }
1142
1143 /**
1144 * Inserts the HTML specified as a string at the start
1145 * of the element.
1146 *
1147 * <p>Consider the following structure (the <code>elem</code>
1148 * parameter is <b>in bold</b>).</p>
1149 *
1150 * <pre>
1151 * <body>
1152 * |
1153 * <b><div></b>
1154 * / \
1155 * <p> <p>
1156 * </pre>
1157 *
1158 * <p>Invoking <code>insertAfterStart(elem,
1159 * "<ul><li>")</code> results in the following structure
1160 * (new elements are <font style="color: red;">in red</font>).</p>
1161 *
1162 * <pre>
1163 * <body>
1164 * |
1165 * <b><div></b>
1166 * / | \
1167 * <font style="color: red;"><ul></font> <p> <p>
1168 * /
1169 * <font style="color: red;"><li></font>
1170 * </pre>
1171 *
1172 * <p>Unlike the <code>insertBeforeStart</code> method, new
1173 * elements become <em>children</em> of the specified element,
1174 * not siblings.</p>
1175 *
1176 * <p>Parameter <code>elem</code> must not be a leaf element,
1177 * otherwise an <code>IllegalArgumentException</code> is thrown.
1178 * If either <code>elem</code> or <code>htmlText</code> parameter
1179 * is <code>null</code>, no changes are made to the document.</p>
1180 *
1181 * <p>For this to work correctly, the document must have an
1182 * <code>HTMLEditorKit.Parser</code> set. This will be the case
1183 * if the document was created from an HTMLEditorKit via the
1184 * <code>createDefaultDocument</code> method.</p>
1185 *
1186 * @param elem the branch element to be the root for the new text
1187 * @param htmlText the string to be parsed and assigned to <code>elem</code>
1188 * @throws IllegalArgumentException if <code>elem</code> is a leaf
1189 * @throws IllegalStateException if an HTMLEditorKit.Parser has not
1212 * Inserts the HTML specified as a string at the end of
1213 * the element.
1214 *
1215 * <p> If <code>elem</code>'s children are leaves, and the
1216 * character at a <code>elem.getEndOffset() - 1</code> is a newline,
1217 * this will insert before the newline so that there isn't text after
1218 * the newline.</p>
1219 *
1220 * <p>Consider the following structure (the <code>elem</code>
1221 * parameter is <b>in bold</b>).</p>
1222 *
1223 * <pre>
1224 * <body>
1225 * |
1226 * <b><div></b>
1227 * / \
1228 * <p> <p>
1229 * </pre>
1230 *
1231 * <p>Invoking <code>insertBeforeEnd(elem, "<ul><li>")</code>
1232 * results in the following structure (new elements are <font
1233 * style="color: red;">in red</font>).</p>
1234 *
1235 * <pre>
1236 * <body>
1237 * |
1238 * <b><div></b>
1239 * / | \
1240 * <p> <p> <font style="color: red;"><ul></font>
1241 * \
1242 * <font style="color: red;"><li></font>
1243 * </pre>
1244 *
1245 * <p>Unlike the <code>insertAfterEnd</code> method, new elements
1246 * become <em>children</em> of the specified element, not
1247 * siblings.</p>
1248 *
1249 * <p>Parameter <code>elem</code> must not be a leaf element,
1250 * otherwise an <code>IllegalArgumentException</code> is thrown.
1251 * If either <code>elem</code> or <code>htmlText</code> parameter
1252 * is <code>null</code>, no changes are made to the document.</p>
1253 *
1254 * <p>For this to work correctly, the document must have an
1255 * <code>HTMLEditorKit.Parser</code> set. This will be the case
1256 * if the document was created from an HTMLEditorKit via the
1257 * <code>createDefaultDocument</code> method.</p>
1258 *
1259 * @param elem the element to be the root for the new text
1260 * @param htmlText the string to be parsed and assigned to <code>elem</code>
1261 * @throws IllegalArgumentException if <code>elem</code> is a leaf
1262 * @throws IllegalStateException if an HTMLEditorKit.Parser has not
1283 }
1284 }
1285
1286 /**
1287 * Inserts the HTML specified as a string before the start of
1288 * the given element.
1289 *
1290 * <p>Consider the following structure (the <code>elem</code>
1291 * parameter is <b>in bold</b>).</p>
1292 *
1293 * <pre>
1294 * <body>
1295 * |
1296 * <b><div></b>
1297 * / \
1298 * <p> <p>
1299 * </pre>
1300 *
1301 * <p>Invoking <code>insertBeforeStart(elem,
1302 * "<ul><li>")</code> results in the following structure
1303 * (new elements are <font style="color: red;">in red</font>).</p>
1304 *
1305 * <pre>
1306 * <body>
1307 * / \
1308 * <font style="color: red;"><ul></font> <b><div></b>
1309 * / / \
1310 * <font style="color: red;"><li></font> <p> <p>
1311 * </pre>
1312 *
1313 * <p>Unlike the <code>insertAfterStart</code> method, new
1314 * elements become <em>siblings</em> of the specified element, not
1315 * children.</p>
1316 *
1317 * <p>If either <code>elem</code> or <code>htmlText</code>
1318 * parameter is <code>null</code>, no changes are made to the
1319 * document.</p>
1320 *
1321 * <p>For this to work correctly, the document must have an
1322 * <code>HTMLEditorKit.Parser</code> set. This will be the case
1323 * if the document was created from an HTMLEditorKit via the
1324 * <code>createDefaultDocument</code> method.</p>
1325 *
1326 * @param elem the element the content is inserted before
1327 * @param htmlText the string to be parsed and inserted before <code>elem</code>
1328 * @throws IllegalStateException if an HTMLEditorKit.Parser has not
1329 * been set on the document
1330 * @throws BadLocationException if insertion is impossible because of
1343 }
1344 }
1345 }
1346
1347 /**
1348 * Inserts the HTML specified as a string after the end of the
1349 * given element.
1350 *
1351 * <p>Consider the following structure (the <code>elem</code>
1352 * parameter is <b>in bold</b>).</p>
1353 *
1354 * <pre>
1355 * <body>
1356 * |
1357 * <b><div></b>
1358 * / \
1359 * <p> <p>
1360 * </pre>
1361 *
1362 * <p>Invoking <code>insertAfterEnd(elem, "<ul><li>")</code>
1363 * results in the following structure (new elements are <font
1364 * style="color: red;">in red</font>).</p>
1365 *
1366 * <pre>
1367 * <body>
1368 * / \
1369 * <b><div></b> <font style="color: red;"><ul></font>
1370 * / \ \
1371 * <p> <p> <font style="color: red;"><li></font>
1372 * </pre>
1373 *
1374 * <p>Unlike the <code>insertBeforeEnd</code> method, new elements
1375 * become <em>siblings</em> of the specified element, not
1376 * children.</p>
1377 *
1378 * <p>If either <code>elem</code> or <code>htmlText</code>
1379 * parameter is <code>null</code>, no changes are made to the
1380 * document.</p>
1381 *
1382 * <p>For this to work correctly, the document must have an
1383 * <code>HTMLEditorKit.Parser</code> set. This will be the case
1384 * if the document was created from an HTMLEditorKit via the
1385 * <code>createDefaultDocument</code> method.</p>
1386 *
1387 * @param elem the element the content is inserted after
1388 * @param htmlText the string to be parsed and inserted after <code>elem</code>
1389 * @throws IllegalStateException if an HTMLEditorKit.Parser has not
1390 * been set on the document
1391 * @throws BadLocationException if insertion is impossible because of
|
1 /*
2 * Copyright (c) 1997, 2017, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
982
983 /**
984 * Replaces the children of the given element with the contents
985 * specified as an HTML string.
986 *
987 * <p>This will be seen as at least two events, n inserts followed by
988 * a remove.</p>
989 *
990 * <p>Consider the following structure (the <code>elem</code>
991 * parameter is <b>in bold</b>).</p>
992 *
993 * <pre>
994 * <body>
995 * |
996 * <b><div></b>
997 * / \
998 * <p> <p>
999 * </pre>
1000 *
1001 * <p>Invoking <code>setInnerHTML(elem, "<ul><li>")</code>
1002 * results in the following structure (new elements are <span
1003 * style="color: red;">in red</span>).</p>
1004 *
1005 * <pre>
1006 * <body>
1007 * |
1008 * <b><div></b>
1009 * \
1010 * <span style="color: red;"><ul></span>
1011 * \
1012 * <span style="color: red;"><li></span>
1013 * </pre>
1014 *
1015 * <p>Parameter <code>elem</code> must not be a leaf element,
1016 * otherwise an <code>IllegalArgumentException</code> is thrown.
1017 * If either <code>elem</code> or <code>htmlText</code> parameter
1018 * is <code>null</code>, no changes are made to the document.</p>
1019 *
1020 * <p>For this to work correctly, the document must have an
1021 * <code>HTMLEditorKit.Parser</code> set. This will be the case
1022 * if the document was created from an HTMLEditorKit via the
1023 * <code>createDefaultDocument</code> method.</p>
1024 *
1025 * @param elem the branch element whose children will be replaced
1026 * @param htmlText the string to be parsed and assigned to <code>elem</code>
1027 * @throws IllegalArgumentException if <code>elem</code> is a leaf
1028 * @throws IllegalStateException if an <code>HTMLEditorKit.Parser</code>
1029 * has not been defined
1030 * @throws BadLocationException if replacement is impossible because of
1031 * a structural issue
1032 * @throws IOException if an I/O exception occurs
1066 *
1067 * <p>If you try to replace the element at length you will most
1068 * likely end up with two elements, eg
1069 * <code>setOuterHTML(getCharacterElement (getLength()),
1070 * "blah")</code> will result in two leaf elements at the end, one
1071 * representing 'blah', and the other representing the end
1072 * element.</p>
1073 *
1074 * <p>Consider the following structure (the <code>elem</code>
1075 * parameter is <b>in bold</b>).</p>
1076 *
1077 * <pre>
1078 * <body>
1079 * |
1080 * <b><div></b>
1081 * / \
1082 * <p> <p>
1083 * </pre>
1084 *
1085 * <p>Invoking <code>setOuterHTML(elem, "<ul><li>")</code>
1086 * results in the following structure (new elements are <span
1087 * style="color: red;">in red</span>).</p>
1088 *
1089 * <pre>
1090 * <body>
1091 * |
1092 * <span style="color: red;"><ul></span>
1093 * \
1094 * <span style="color: red;"><li></span>
1095 * </pre>
1096 *
1097 * <p>If either <code>elem</code> or <code>htmlText</code>
1098 * parameter is <code>null</code>, no changes are made to the
1099 * document.</p>
1100 *
1101 * <p>For this to work correctly, the document must have an
1102 * HTMLEditorKit.Parser set. This will be the case if the document
1103 * was created from an HTMLEditorKit via the
1104 * <code>createDefaultDocument</code> method.</p>
1105 *
1106 * @param elem the element to replace
1107 * @param htmlText the string to be parsed and inserted in place of <code>elem</code>
1108 * @throws IllegalStateException if an HTMLEditorKit.Parser has not
1109 * been set
1110 * @throws BadLocationException if replacement is impossible because of
1111 * a structural issue
1112 * @throws IOException if an I/O exception occurs
1113 * @since 1.3
1114 */
1140 }
1141 }
1142
1143 /**
1144 * Inserts the HTML specified as a string at the start
1145 * of the element.
1146 *
1147 * <p>Consider the following structure (the <code>elem</code>
1148 * parameter is <b>in bold</b>).</p>
1149 *
1150 * <pre>
1151 * <body>
1152 * |
1153 * <b><div></b>
1154 * / \
1155 * <p> <p>
1156 * </pre>
1157 *
1158 * <p>Invoking <code>insertAfterStart(elem,
1159 * "<ul><li>")</code> results in the following structure
1160 * (new elements are <span style="color: red;">in red</span>).</p>
1161 *
1162 * <pre>
1163 * <body>
1164 * |
1165 * <b><div></b>
1166 * / | \
1167 * <span style="color: red;"><ul></span> <p> <p>
1168 * /
1169 * <span style="color: red;"><li></span>
1170 * </pre>
1171 *
1172 * <p>Unlike the <code>insertBeforeStart</code> method, new
1173 * elements become <em>children</em> of the specified element,
1174 * not siblings.</p>
1175 *
1176 * <p>Parameter <code>elem</code> must not be a leaf element,
1177 * otherwise an <code>IllegalArgumentException</code> is thrown.
1178 * If either <code>elem</code> or <code>htmlText</code> parameter
1179 * is <code>null</code>, no changes are made to the document.</p>
1180 *
1181 * <p>For this to work correctly, the document must have an
1182 * <code>HTMLEditorKit.Parser</code> set. This will be the case
1183 * if the document was created from an HTMLEditorKit via the
1184 * <code>createDefaultDocument</code> method.</p>
1185 *
1186 * @param elem the branch element to be the root for the new text
1187 * @param htmlText the string to be parsed and assigned to <code>elem</code>
1188 * @throws IllegalArgumentException if <code>elem</code> is a leaf
1189 * @throws IllegalStateException if an HTMLEditorKit.Parser has not
1212 * Inserts the HTML specified as a string at the end of
1213 * the element.
1214 *
1215 * <p> If <code>elem</code>'s children are leaves, and the
1216 * character at a <code>elem.getEndOffset() - 1</code> is a newline,
1217 * this will insert before the newline so that there isn't text after
1218 * the newline.</p>
1219 *
1220 * <p>Consider the following structure (the <code>elem</code>
1221 * parameter is <b>in bold</b>).</p>
1222 *
1223 * <pre>
1224 * <body>
1225 * |
1226 * <b><div></b>
1227 * / \
1228 * <p> <p>
1229 * </pre>
1230 *
1231 * <p>Invoking <code>insertBeforeEnd(elem, "<ul><li>")</code>
1232 * results in the following structure (new elements are <span
1233 * style="color: red;">in red</span>).</p>
1234 *
1235 * <pre>
1236 * <body>
1237 * |
1238 * <b><div></b>
1239 * / | \
1240 * <p> <p> <span style="color: red;"><ul></span>
1241 * \
1242 * <span style="color: red;"><li></span>
1243 * </pre>
1244 *
1245 * <p>Unlike the <code>insertAfterEnd</code> method, new elements
1246 * become <em>children</em> of the specified element, not
1247 * siblings.</p>
1248 *
1249 * <p>Parameter <code>elem</code> must not be a leaf element,
1250 * otherwise an <code>IllegalArgumentException</code> is thrown.
1251 * If either <code>elem</code> or <code>htmlText</code> parameter
1252 * is <code>null</code>, no changes are made to the document.</p>
1253 *
1254 * <p>For this to work correctly, the document must have an
1255 * <code>HTMLEditorKit.Parser</code> set. This will be the case
1256 * if the document was created from an HTMLEditorKit via the
1257 * <code>createDefaultDocument</code> method.</p>
1258 *
1259 * @param elem the element to be the root for the new text
1260 * @param htmlText the string to be parsed and assigned to <code>elem</code>
1261 * @throws IllegalArgumentException if <code>elem</code> is a leaf
1262 * @throws IllegalStateException if an HTMLEditorKit.Parser has not
1283 }
1284 }
1285
1286 /**
1287 * Inserts the HTML specified as a string before the start of
1288 * the given element.
1289 *
1290 * <p>Consider the following structure (the <code>elem</code>
1291 * parameter is <b>in bold</b>).</p>
1292 *
1293 * <pre>
1294 * <body>
1295 * |
1296 * <b><div></b>
1297 * / \
1298 * <p> <p>
1299 * </pre>
1300 *
1301 * <p>Invoking <code>insertBeforeStart(elem,
1302 * "<ul><li>")</code> results in the following structure
1303 * (new elements are <span style="color: red;">in red</span>).</p>
1304 *
1305 * <pre>
1306 * <body>
1307 * / \
1308 * <span style="color: red;"><ul></span> <b><div></b>
1309 * / / \
1310 * <span style="color: red;"><li></span> <p> <p>
1311 * </pre>
1312 *
1313 * <p>Unlike the <code>insertAfterStart</code> method, new
1314 * elements become <em>siblings</em> of the specified element, not
1315 * children.</p>
1316 *
1317 * <p>If either <code>elem</code> or <code>htmlText</code>
1318 * parameter is <code>null</code>, no changes are made to the
1319 * document.</p>
1320 *
1321 * <p>For this to work correctly, the document must have an
1322 * <code>HTMLEditorKit.Parser</code> set. This will be the case
1323 * if the document was created from an HTMLEditorKit via the
1324 * <code>createDefaultDocument</code> method.</p>
1325 *
1326 * @param elem the element the content is inserted before
1327 * @param htmlText the string to be parsed and inserted before <code>elem</code>
1328 * @throws IllegalStateException if an HTMLEditorKit.Parser has not
1329 * been set on the document
1330 * @throws BadLocationException if insertion is impossible because of
1343 }
1344 }
1345 }
1346
1347 /**
1348 * Inserts the HTML specified as a string after the end of the
1349 * given element.
1350 *
1351 * <p>Consider the following structure (the <code>elem</code>
1352 * parameter is <b>in bold</b>).</p>
1353 *
1354 * <pre>
1355 * <body>
1356 * |
1357 * <b><div></b>
1358 * / \
1359 * <p> <p>
1360 * </pre>
1361 *
1362 * <p>Invoking <code>insertAfterEnd(elem, "<ul><li>")</code>
1363 * results in the following structure (new elements are <span
1364 * style="color: red;">in red</span>).</p>
1365 *
1366 * <pre>
1367 * <body>
1368 * / \
1369 * <b><div></b> <span style="color: red;"><ul></span>
1370 * / \ \
1371 * <p> <p> <span style="color: red;"><li></span>
1372 * </pre>
1373 *
1374 * <p>Unlike the <code>insertBeforeEnd</code> method, new elements
1375 * become <em>siblings</em> of the specified element, not
1376 * children.</p>
1377 *
1378 * <p>If either <code>elem</code> or <code>htmlText</code>
1379 * parameter is <code>null</code>, no changes are made to the
1380 * document.</p>
1381 *
1382 * <p>For this to work correctly, the document must have an
1383 * <code>HTMLEditorKit.Parser</code> set. This will be the case
1384 * if the document was created from an HTMLEditorKit via the
1385 * <code>createDefaultDocument</code> method.</p>
1386 *
1387 * @param elem the element the content is inserted after
1388 * @param htmlText the string to be parsed and inserted after <code>elem</code>
1389 * @throws IllegalStateException if an HTMLEditorKit.Parser has not
1390 * been set on the document
1391 * @throws BadLocationException if insertion is impossible because of
|