1. /*
  2. * @(#)Element.java 1.23 03/12/19
  3. *
  4. * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
  5. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
  6. */
  7. package javax.swing.text;
  8. /**
  9. * Interface to describe a structural piece of a document. It
  10. * is intended to capture the spirit of an SGML element.
  11. *
  12. * @author Timothy Prinzing
  13. * @version 1.23 12/19/03
  14. */
  15. public interface Element {
  16. /**
  17. * Fetches the document associated with this element.
  18. *
  19. * @return the document
  20. */
  21. public Document getDocument();
  22. /**
  23. * Fetches the parent element. If the element is a root level
  24. * element returns <code>null</code>.
  25. *
  26. * @return the parent element
  27. */
  28. public Element getParentElement();
  29. /**
  30. * Fetches the name of the element. If the element is used to
  31. * represent some type of structure, this would be the type
  32. * name.
  33. *
  34. * @return the element name
  35. */
  36. public String getName();
  37. /**
  38. * Fetches the collection of attributes this element contains.
  39. *
  40. * @return the attributes for the element
  41. */
  42. public AttributeSet getAttributes();
  43. /**
  44. * Fetches the offset from the beginning of the document
  45. * that this element begins at. If this element has
  46. * children, this will be the offset of the first child.
  47. * As a document position, there is an implied forward bias.
  48. *
  49. * @return the starting offset >= 0 and < getEndOffset();
  50. * @see Document
  51. * @see AbstractDocument
  52. */
  53. public int getStartOffset();
  54. /**
  55. * Fetches the offset from the beginning of the document
  56. * that this element ends at. If this element has
  57. * children, this will be the end offset of the last child.
  58. * As a document position, there is an implied backward bias.
  59. * <p>
  60. * All the default <code>Document</code> implementations
  61. * descend from <code>AbstractDocument</code>.
  62. * <code>AbstractDocument</code> models an implied break at the end of
  63. * the document. As a result of this, it is possible for this to
  64. * return a value greater than the length of the document.
  65. *
  66. * @return the ending offset > getStartOffset() and
  67. * <= getDocument().getLength() + 1
  68. * @see Document
  69. * @see AbstractDocument
  70. */
  71. public int getEndOffset();
  72. /**
  73. * Gets the child element index closest to the given offset.
  74. * The offset is specified relative to the beginning of the
  75. * document. Returns <code>-1</code> if the
  76. * <code>Element</code> is a leaf, otherwise returns
  77. * the index of the <code>Element</code> that best represents
  78. * the given location. Returns <code>0</code> if the location
  79. * is less than the start offset. Returns
  80. * <code>getElementCount() - 1</code> if the location is
  81. * greater than or equal to the end offset.
  82. *
  83. * @param offset the specified offset >= 0
  84. * @return the element index >= 0
  85. */
  86. public int getElementIndex(int offset);
  87. /**
  88. * Gets the number of child elements contained by this element.
  89. * If this element is a leaf, a count of zero is returned.
  90. *
  91. * @return the number of child elements >= 0
  92. */
  93. public int getElementCount();
  94. /**
  95. * Fetches the child element at the given index.
  96. *
  97. * @param index the specified index >= 0
  98. * @return the child element
  99. */
  100. public Element getElement(int index);
  101. /**
  102. * Is this element a leaf element? An element that
  103. * <i>may</i> have children, even if it currently
  104. * has no children, would return <code>false</code>.
  105. *
  106. * @return true if a leaf element else false
  107. */
  108. public boolean isLeaf();
  109. }