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 /**
  28  * Interface to describe a structural piece of a document.  It
  29  * is intended to capture the spirit of an SGML element.
  30  *
  31  * @author  Timothy Prinzing
  32  */
  33 public interface Element {
  34 
  35     /**
  36      * Fetches the document associated with this element.
  37      *
  38      * @return the document
  39      */
  40     public Document getDocument();
  41 
  42     /**
  43      * Fetches the parent element.  If the element is a root level
  44      * element returns {@code null}.
  45      *
  46      * @return the parent element
  47      */
  48     public Element getParentElement();
  49 
  50     /**
  51      * Fetches the name of the element.  If the element is used to
  52      * represent some type of structure, this would be the type
  53      * name.
  54      *
  55      * @return the element name
  56      */
  57     public String getName();
  58 
  59     /**
  60      * Fetches the collection of attributes this element contains.
  61      *
  62      * @return the attributes for the element
  63      */
  64     public AttributeSet getAttributes();
  65 
  66     /**
  67      * Fetches the offset from the beginning of the document
  68      * that this element begins at.  If this element has
  69      * children, this will be the offset of the first child.
  70      * As a document position, there is an implied forward bias.
  71      *
  72      * @return the starting offset >= 0 and < getEndOffset();
  73      * @see Document
  74      * @see AbstractDocument
  75      */
  76     public int getStartOffset();
  77 
  78     /**
  79      * Fetches the offset from the beginning of the document
  80      * that this element ends at.  If this element has
  81      * children, this will be the end offset of the last child.
  82      * As a document position, there is an implied backward bias.
  83      * <p>
  84      * All the default {@code Document} implementations
  85      * descend from {@code AbstractDocument}.
  86      * {@code AbstractDocument} models an implied break at the end of
  87      * the document. As a result of this, it is possible for this to
  88      * return a value greater than the length of the document.
  89      *
  90      * @return the ending offset &gt; getStartOffset() and
  91      *     &lt;= getDocument().getLength() + 1
  92      * @see Document
  93      * @see AbstractDocument
  94      */
  95     public int getEndOffset();
  96 
  97     /**
  98      * Gets the child element index closest to the given offset.
  99      * The offset is specified relative to the beginning of the
 100      * document.  Returns {@code -1} if the
 101      * {@code Element} is a leaf, otherwise returns
 102      * the index of the {@code Element} that best represents
 103      * the given location.  Returns {@code 0} if the location
 104      * is less than the start offset. Returns
 105      * {@code getElementCount() - 1} if the location is
 106      * greater than or equal to the end offset.
 107      *
 108      * @param offset the specified offset &gt;= 0
 109      * @return the element index &gt;= 0
 110      */
 111     public int getElementIndex(int offset);
 112 
 113     /**
 114      * Gets the number of child elements contained by this element.
 115      * If this element is a leaf, a count of zero is returned.
 116      *
 117      * @return the number of child elements &gt;= 0
 118      */
 119     public int getElementCount();
 120 
 121     /**
 122      * Fetches the child element at the given index.
 123      *
 124      * @param index the specified index &gt;= 0
 125      * @return the child element
 126      */
 127     public Element getElement(int index);
 128 
 129     /**
 130      * Is this element a leaf element? An element that
 131      * <i>may</i> have children, even if it currently
 132      * has no children, would return {@code false}.
 133      *
 134      * @return true if a leaf element else false
 135      */
 136     public boolean isLeaf();
 137 
 138 
 139 }
--- EOF ---