1 /* 2 * Copyright (c) 1997, 2013, 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 23 * questions. 24 */ 25 package javax.swing.text; 26 27 import java.awt.Font; 28 import java.awt.Color; 29 30 /** 31 * Interface for a generic styled document. 32 * 33 * @author Timothy Prinzing 34 */ 35 public interface StyledDocument extends Document { 36 37 /** 38 * Adds a new style into the logical style hierarchy. Style attributes 39 * resolve from bottom up so an attribute specified in a child 40 * will override an attribute specified in the parent. 41 * 42 * @param nm the name of the style (must be unique within the 43 * collection of named styles). The name may be null if the style 44 * is unnamed, but the caller is responsible 45 * for managing the reference returned as an unnamed style can't 46 * be fetched by name. An unnamed style may be useful for things 47 * like character attribute overrides such as found in a style 48 * run. 49 * @param parent the parent style. This may be null if unspecified 50 * attributes need not be resolved in some other style. 51 * @return the style 52 */ addStyle(String nm, Style parent)53 public Style addStyle(String nm, Style parent); 54 55 /** 56 * Removes a named style previously added to the document. 57 * 58 * @param nm the name of the style to remove 59 */ removeStyle(String nm)60 public void removeStyle(String nm); 61 62 /** 63 * Fetches a named style previously added. 64 * 65 * @param nm the name of the style 66 * @return the style 67 */ getStyle(String nm)68 public Style getStyle(String nm); 69 70 /** 71 * Changes the content element attributes used for the given range of 72 * existing content in the document. All of the attributes 73 * defined in the given Attributes argument are applied to the 74 * given range. This method can be used to completely remove 75 * all content level attributes for the given range by 76 * giving an Attributes argument that has no attributes defined 77 * and setting replace to true. 78 * 79 * @param offset the start of the change >= 0 80 * @param length the length of the change >= 0 81 * @param s the non-null attributes to change to. Any attributes 82 * defined will be applied to the text for the given range. 83 * @param replace indicates whether or not the previous 84 * attributes should be cleared before the new attributes 85 * as set. If true, the operation will replace the 86 * previous attributes entirely. If false, the new 87 * attributes will be merged with the previous attributes. 88 */ setCharacterAttributes(int offset, int length, AttributeSet s, boolean replace)89 public void setCharacterAttributes(int offset, int length, AttributeSet s, boolean replace); 90 91 /** 92 * Sets paragraph attributes. 93 * 94 * @param offset the start of the change >= 0 95 * @param length the length of the change >= 0 96 * @param s the non-null attributes to change to. Any attributes 97 * defined will be applied to the text for the given range. 98 * @param replace indicates whether or not the previous 99 * attributes should be cleared before the new attributes 100 * are set. If true, the operation will replace the 101 * previous attributes entirely. If false, the new 102 * attributes will be merged with the previous attributes. 103 */ setParagraphAttributes(int offset, int length, AttributeSet s, boolean replace)104 public void setParagraphAttributes(int offset, int length, AttributeSet s, boolean replace); 105 106 /** 107 * Sets the logical style to use for the paragraph at the 108 * given position. If attributes aren't explicitly set 109 * for character and paragraph attributes they will resolve 110 * through the logical style assigned to the paragraph, which 111 * in turn may resolve through some hierarchy completely 112 * independent of the element hierarchy in the document. 113 * 114 * @param pos the starting position >= 0 115 * @param s the style to set 116 */ setLogicalStyle(int pos, Style s)117 public void setLogicalStyle(int pos, Style s); 118 119 /** 120 * Gets a logical style for a given position in a paragraph. 121 * 122 * @param p the position >= 0 123 * @return the style 124 */ getLogicalStyle(int p)125 public Style getLogicalStyle(int p); 126 127 /** 128 * Gets the element that represents the paragraph that 129 * encloses the given offset within the document. 130 * 131 * @param pos the offset >= 0 132 * @return the element 133 */ getParagraphElement(int pos)134 public Element getParagraphElement(int pos); 135 136 /** 137 * Gets the element that represents the character that 138 * is at the given offset within the document. 139 * 140 * @param pos the offset >= 0 141 * @return the element 142 */ getCharacterElement(int pos)143 public Element getCharacterElement(int pos); 144 145 146 /** 147 * Takes a set of attributes and turn it into a foreground color 148 * specification. This might be used to specify things 149 * like brighter, more hue, etc. 150 * 151 * @param attr the set of attributes 152 * @return the color 153 */ getForeground(AttributeSet attr)154 public Color getForeground(AttributeSet attr); 155 156 /** 157 * Takes a set of attributes and turn it into a background color 158 * specification. This might be used to specify things 159 * like brighter, more hue, etc. 160 * 161 * @param attr the set of attributes 162 * @return the color 163 */ getBackground(AttributeSet attr)164 public Color getBackground(AttributeSet attr); 165 166 /** 167 * Takes a set of attributes and turn it into a font 168 * specification. This can be used to turn things like 169 * family, style, size, etc into a font that is available 170 * on the system the document is currently being used on. 171 * 172 * @param attr the set of attributes 173 * @return the font 174 */ getFont(AttributeSet attr)175 public Font getFont(AttributeSet attr); 176 177 } 178