View Javadoc
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       */
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       */
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       */
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       */
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      */
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      */
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      */
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      */
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      */
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      */
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      */
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      */
175     public Font getFont(AttributeSet attr);
176 
177 }