Package com.arbortext.epic

Interface ARange

All Known Implementing Classes:
RangeImpl
public interface ARange
The PTC Arbortext extension to the W3C DOM Range interface.

ARange adds four read-only attributes (startOID , startPos, endOID, endPos) that give the start and end points of the Range as strings that may be spliced into ACL commands. Note that ACL represents a point as an OID/POS pair.

PTC Arbortext Editor (and PTC Arbortext Publishing Engine) and the DOM represent ranges differently. Therefore, the individual components of a DOM range endpoint (attributes startNode, startOffset) and PTC Arbortext endpoint (attributes startOID, startPos) may differ. That is, the OID indicated by startOID will not necessarily be the starting OID for the node indicated by startNode, and the integer value startOffset will not necessarily be equal to the integer value startPos. Nor will there necessarily be equivalences between endNode and endOID or endOffset and endPos.

We only guarantee that the point in the document represented by the pair (startNode, startOffset) will be the same point as that indicated by the pair (startOID, startPos) and that the point represented by the pair ( endNode, endOffset) will be the same point as that represented by the pair (endOID, endPos).

The DOM allows the endpoint of a range to be within a processing instruction; PTC Arbortext products do not. If a DOM (node, offset) pair is located within a processing instruction, the corresponding (OID, pos) pair will indicate the point just before the start of the processing instruction (if the [node, offset] is the start of the range) or just after the end of the processing instruction (if the [node, offset] is the end of the range).

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    MARKUP_CHAR
    Non-ASCII characters are converted according to the current writenonasciichar set option.
    static final int
    MARKUP_EXPAND_XINCLUDE
    Force XML inclusions to be replaced by their contents.
    static final int
    MARKUP_FORCE_PI
    Force PTC Arbortext processing instructions to be included.
    static final int
    MARKUP_FORCE_SGML
    Use SGML syntax in the string returned even if the Range is in an XML document.
    static final int
    MARKUP_FORCE_XML
    Use XML syntax in the string returned even if the Range is in an SGML document.
    static final int
    MARKUP_HEADER
    Include the XML or SGML header associated with the Range.
    static final int
    MARKUP_NO_PI
    Suppress PTC Arbortext processing instructions.

  • Method Summary

    Modifier and Type
    Method
    Description
    short
    canInsertNode(Node node)
    This method indicates whether a Node can be inserted at a position specified by the start of this Range such that the result is compliant with VAL_SCHEMA validity type.
    short
    canInsertNodeWithFixup(Node node)
    This method indicates whether a Node can be inserted at a position specified by the start of this Range such that the result is compliant with VAL_SCHEMA validity type.
    NameList
    getAllowedInsertElements()
    Elements that can be inserted into the Document or DocumentFragment at the start of the Range such that the result will be compliant with VAL_SCHEMA validity type.
    NameList
    getAllowedSurroundElements()
    Elements that can surround the Range such that the result will be compliant with VAL_SCHEMA validity type.
    String
    getContextString()
    This function returns a DOMString describing the context of the start of this Range.
    String
    getEndOID()
    The end OID of the Range.
    String
    getEndPos()
    The end position (in ACL) of the Range.
    String
    getStartOID()
    The start OID of the Range.
    String
    getStartPos()
    The start position (in ACL) of the Range.
    Range
    insertNodeWithFixup(Node node)
    This method inserts a Node to the position specified by the start of this Range.
    void
    insertParsedString(String text)
    Parses text and inserts the resulting DOM objects into a document at the location indicated by the start of the Range.
    String
    toMarkupString()
    Returns the contents of a Range as a string.
    String
    toMarkupStringEx()
    Method overload which omits the last parameter.
    String
    toMarkupStringEx(int flags)
    Returns the contents of a Range as a string, with control over the markup.

  • Field Details

    • MARKUP_HEADER

      static final int MARKUP_HEADER
      Include the XML or SGML header associated with the Range. If the Range does not include the entire document, this will be a fragment header.
      See Also:

    • MARKUP_FORCE_XML

      static final int MARKUP_FORCE_XML
      Use XML syntax in the string returned even if the Range is in an SGML document.
      See Also:

    • MARKUP_FORCE_SGML

      static final int MARKUP_FORCE_SGML
      Use SGML syntax in the string returned even if the Range is in an XML document.
      See Also:

    • MARKUP_NO_PI

      static final int MARKUP_NO_PI
      Suppress PTC Arbortext processing instructions. PTC Arbortext processing instructions can also be suppressed using the writepi set option.
      See Also:

    • MARKUP_FORCE_PI

      static final int MARKUP_FORCE_PI
      Force PTC Arbortext processing instructions to be included. This option overrides the MARKUP_NO_PI option and the writepi set option.
      See Also:

    • MARKUP_EXPAND_XINCLUDE

      static final int MARKUP_EXPAND_XINCLUDE
      Force XML inclusions to be replaced by their contents.
      See Also:

    • MARKUP_CHAR

      static final int MARKUP_CHAR
      Non-ASCII characters are converted according to the current writenonasciichar set option. If the entityoutputconvert set option is also on, then character entities will also be output according to the writenonasciichar set option.
      See Also:

  • Method Details

    • getStartOID

      String getStartOID() throws DOMException
      The start OID of the Range. Note that the OID indicated by the startOID is not necessarily the same as the starting OID for the node indicated by the startNode.
      Throws:
      DOMException - INVALID_STATE_ERR: Raised if the Range has already been detached.
      Since:
      Epic 4.0

    • getStartPos

      String getStartPos() throws DOMException
      The start position (in ACL) of the Range. Note that the position indicated by the startPos is not necessarily equal to the value of startOffset.
      Throws:
      DOMException - INVALID_STATE_ERR: Raised if the Range has already been detached.
      Since:
      Epic 4.0

    • getEndOID

      String getEndOID() throws DOMException
      The end OID of the Range. Note that the OID indicated by the endOID is not necessarily the same as the ending OID for the node indicated by the endNode.
      Throws:
      DOMException - INVALID_STATE_ERR: Raised if the Range has already been detached.
      Since:
      Epic 4.0

    • getEndPos

      String getEndPos() throws DOMException
      The end position (in ACL) of the Range. Note that the position indicated by the endPos is not necessarily equal to the value of endOffset.
      Throws:
      DOMException - INVALID_STATE_ERR: Raised if the Range has already been detached.
      Since:
      Epic 4.0

    • insertParsedString

      void insertParsedString(String text) throws AOMException
      Parses text and inserts the resulting DOM objects into a document at the location indicated by the start of the Range.
      Parameters:
      text - The text to be inserted. Markup is interpreted as XML or SGML according to the target document. If an empty string, this method does nothing.
      Throws:
      AOMException - Raised if the method detects an error, for example, the insertion is not permitted due to context checking.
      Since:
      Epic 4.3

    • toMarkupString

      String toMarkupString() throws DOMException
      Returns the contents of a Range as a string. This string contains the character data and markup representing the entire contents of the range.
      Returns:
      The contents of the Range.
      Throws:
      DOMException - INVALID_STATE_ERR: Raised if the Range has already been detached.
      Since:
      Epic 4.3

    • getAllowedInsertElements

      NameList getAllowedInsertElements()
      Elements that can be inserted into the Document or DocumentFragment at the start of the Range such that the result will be compliant with VAL_SCHEMA validity type. If the start container is a Text node it will be assumed to be split into two text nodes and the list of elements valid between them will be returned.
      Since:
      Epic 5.0

    • getAllowedSurroundElements

      NameList getAllowedSurroundElements()
      Elements that can surround the Range such that the result will be compliant with VAL_SCHEMA validity type.
      Since:
      Epic 5.0

    • getContextString

      String getContextString()
      This function returns a DOMString describing the context of the start of this Range. This string consists of a list of element names and parentheses, such as: doc(body(chapter(title()para0(title()para( The left parenthesis following an element name represents a start tag, and the right parenthesis represents the end tag for the corresponding unmatched start tag. If this Range is before the opening start tag or if context checking is not relevant for the current document, a null string will be returned.
      Since:
      Epic 5.0

    • insertNodeWithFixup

      Range insertNodeWithFixup(Node node) throws DOMException, RangeException
      This method inserts a Node to the position specified by the start of this Range. It will try to add required ancestors or descendents to make context compliant with VAL_SCHEMA validity type. If the start container of the range is a text node it will be split and the node will be inserted between the two resulting text nodes.
      Parameters:
      node - The Node to be inserted.
      Returns:
      The Range inserted.
      Throws:
      DOMException - NO_MODIFICATION_ALLOWED_ERR: Raised if an ancestor container of the start of the Range is read-only.
      WRONG_DOCUMENT_ERR: Raised if newNode and the container of the start of the Range were not created from the same document.
      HIERARCHY_REQUEST_ERR: Raised if the container of the start of the Range is of a type that does not allow children of the type of newNode or if newNode is an ancestor of the container.
      INVALID_STATE_ERR: Raised if detach() has already been invoked on this object.
      RangeException - INVALID_NODE_TYPE_ERR: Raised if newNode is an Attr, Entity, Notation, or Document node.
      Since:
      Epic 5.0

    • canInsertNode

      short canInsertNode(Node node)
      This method indicates whether a Node can be inserted at a position specified by the start of this Range such that the result is compliant with VAL_SCHEMA validity type. If the container is a text node, it will be considered to have been split and the test will be made between the two resulting text nodes.
      Parameters:
      node - The Node to be inserted.
      Returns:
      A validation state constant.
      Since:
      Epic 5.0

    • canInsertNodeWithFixup

      short canInsertNodeWithFixup(Node node)
      This method indicates whether a Node can be inserted at a position specified by the start of this Range such that the result is compliant with VAL_SCHEMA validity type. This test considers adding required ancestors or descendents to make context valid.
      Parameters:
      node - The Node to be inserted.
      Returns:
      A validation state constant.
      Since:
      Epic 5.0

    • toMarkupStringEx

      String toMarkupStringEx(int flags) throws DOMException
      Returns the contents of a Range as a string, with control over the markup. This string contains the character data and markup representing the entire contents of the range.
      Parameters:
      flags - A bitmask that specifies markup options. Constructed by ORing the bits from the MarkupFlags enumeration.
      Returns:
      The contents of the Range.
      Throws:
      DOMException - INVALID_STATE_ERR: Raised if the Range has already been detached.
      Since:
      Epic 5.2

    • toMarkupStringEx

      String toMarkupStringEx() throws DOMException
      Method overload which omits the last parameter.
      Throws:
      DOMException