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.util.Enumeration; 28 29 /** 30 * A collection of unique attributes. This is a read-only, 31 * immutable interface. An attribute is basically a key and 32 * a value assigned to the key. The collection may represent 33 * something like a style run, a logical style, etc. These 34 * are generally used to describe features that will contribute 35 * to some graphical representation such as a font. The 36 * set of possible keys is unbounded and can be anything. 37 * Typically View implementations will respond to attribute 38 * definitions and render something to represent the attributes. 39 * <p> 40 * Attributes can potentially resolve in a hierarchy. If a 41 * key doesn't resolve locally, and a resolving parent 42 * exists, the key will be resolved through the parent. 43 * 44 * @author Timothy Prinzing 45 * @see MutableAttributeSet 46 */ 47 public interface AttributeSet { 48 49 /** 50 * This interface is the type signature that is expected 51 * to be present on any attribute key that contributes to 52 * the determination of what font to use to render some 53 * text. This is not considered to be a closed set, the 54 * definition can change across version of the platform and can 55 * be amended by additional user added entries that 56 * correspond to logical settings that are specific to 57 * some type of content. 58 */ 59 public interface FontAttribute { 60 } 61 62 /** 63 * This interface is the type signature that is expected 64 * to be present on any attribute key that contributes to 65 * presentation of color. 66 */ 67 public interface ColorAttribute { 68 } 69 70 /** 71 * This interface is the type signature that is expected 72 * to be present on any attribute key that contributes to 73 * character level presentation. This would be any attribute 74 * that applies to a so-called <i>run</i> of 75 * style. 76 */ 77 public interface CharacterAttribute { 78 } 79 80 /** 81 * This interface is the type signature that is expected 82 * to be present on any attribute key that contributes to 83 * the paragraph level presentation. 84 */ 85 public interface ParagraphAttribute { 86 } 87 88 /** 89 * Returns the number of attributes that are defined locally in this set. 90 * Attributes that are defined in the parent set are not included. 91 * 92 * @return the number of attributes >= 0 93 */ 94 public int getAttributeCount(); 95 96 /** 97 * Checks whether the named attribute has a value specified in 98 * the set without resolving through another attribute 99 * set. 100 * 101 * @param attrName the attribute name 102 * @return true if the attribute has a value specified 103 */ 104 public boolean isDefined(Object attrName); 105 106 /** 107 * Determines if the two attribute sets are equivalent. 108 * 109 * @param attr an attribute set 110 * @return true if the sets are equivalent 111 */ 112 public boolean isEqual(AttributeSet attr); 113 114 /** 115 * Returns an attribute set that is guaranteed not 116 * to change over time. 117 * 118 * @return a copy of the attribute set 119 */ 120 public AttributeSet copyAttributes(); 121 122 /** 123 * Fetches the value of the given attribute. If the value is not found 124 * locally, the search is continued upward through the resolving 125 * parent (if one exists) until the value is either 126 * found or there are no more parents. If the value is not found, 127 * null is returned. 128 * 129 * @param key the non-null key of the attribute binding 130 * @return the value of the attribute, or {@code null} if not found 131 */ 132 public Object getAttribute(Object key); 133 134 /** 135 * Returns an enumeration over the names of the attributes that are 136 * defined locally in the set. Names of attributes defined in the 137 * resolving parent, if any, are not included. The values of the 138 * <code>Enumeration</code> may be anything and are not constrained to 139 * a particular <code>Object</code> type. 140 * <p> 141 * This method never returns {@code null}. For a set with no attributes, it 142 * returns an empty {@code Enumeration}. 143 * 144 * @return the names 145 */ 146 public Enumeration<?> getAttributeNames(); 147 148 /** 149 * Returns {@code true} if this set defines an attribute with the same 150 * name and an equal value. If such an attribute is not found locally, 151 * it is searched through in the resolving parent hierarchy. 152 * 153 * @param name the non-null attribute name 154 * @param value the value 155 * @return {@code true} if the set defines the attribute with an 156 * equal value, either locally or through its resolving parent 157 * @throws NullPointerException if either {@code name} or 158 * {@code value} is {@code null} 159 */ 160 public boolean containsAttribute(Object name, Object value); 161 162 /** 163 * Returns {@code true} if this set defines all the attributes from the 164 * given set with equal values. If an attribute is not found locally, 165 * it is searched through in the resolving parent hierarchy. 166 * 167 * @param attributes the set of attributes to check against 168 * @return {@code true} if this set defines all the attributes with equal 169 * values, either locally or through its resolving parent 170 * @throws NullPointerException if {@code attributes} is {@code null} 171 */ 172 public boolean containsAttributes(AttributeSet attributes); 173 174 /** 175 * Gets the resolving parent. 176 * 177 * @return the parent 178 */ 179 public AttributeSet getResolveParent(); 180 181 /** 182 * Attribute name used to name the collection of 183 * attributes. 184 */ 185 public static final Object NameAttribute = StyleConstants.NameAttribute; 186 187 /** 188 * Attribute name used to identify the resolving parent 189 * set of attributes, if one is defined. 190 */ 191 public static final Object ResolveAttribute = StyleConstants.ResolveAttribute; 192 193 }