Home » openjdk-7 » javax » swing » text » [javadoc | source]

    1   /*
    2    * Copyright (c) 1997, 2001, 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</code>.
   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</code> implementations
   85        * descend from <code>AbstractDocument</code>.
   86        * <code>AbstractDocument</code> 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 > getStartOffset() and
   91        *     <= 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</code> if the
  101        * <code>Element</code> is a leaf, otherwise returns
  102        * the index of the <code>Element</code> that best represents
  103        * the given location.  Returns <code>0</code> if the location
  104        * is less than the start offset. Returns
  105        * <code>getElementCount() - 1</code> if the location is
  106        * greater than or equal to the end offset.
  107        *
  108        * @param offset the specified offset >= 0
  109        * @return the element index >= 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 >= 0
  118        */
  119       public int getElementCount();
  120   
  121       /**
  122        * Fetches the child element at the given index.
  123        *
  124        * @param index the specified index >= 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</code>.
  133        *
  134        * @return true if a leaf element else false
  135        */
  136       public boolean isLeaf();
  137   
  138   
  139   }

Home » openjdk-7 » javax » swing » text » [javadoc | source]