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