Oxygen XML Editor 16.1 Author API

ro.sync.ecss.extensions.api
Interface AuthorDocumentController


@API(type=NOT_EXTENDABLE,
     src=PUBLIC)
public interface AuthorDocumentController

Provides methods for modifying the Author document.


Method Summary
 void addAuthorListener(AuthorListener listener)
          Add an Author listener to be notified about changes regarding the document and the document structure.
 void addAuthorPersistentHighlightListener(AuthorPersistentHighlightsListener listener)
          Adds a listener to be notified about changes regarding the persistent highlights.
 void addClipboardFragmentProcessor(ClipboardFragmentProcessor clipboardFragmentProcessor)
          Add a processor which can analyze and modify AuthorDocumentFragment objects before they are inserted in the Author.
 void addPersistentHighlightsFilter(AuthorPersistentHighlightsFilter persistentHighlightsFilter)
          Add a persistent highlights filter.
 void addUniqueAttributesProcessor(UniqueAttributesProcessor uniqueAttributesProcessor)
          Add a processor which is asked to automatically generate unique IDs after content has been inserted in the Author.
 void beginCompoundEdit()
          Begin a compound edit.
 void cancelCompoundEdit()
          Cancel the current compound edit.
 AuthorDocumentFragment createDocumentFragment(AuthorNode node, boolean copyContent)
          Create a document fragment containing a copy of the node.
 AuthorDocumentFragment createDocumentFragment(int startOffset, int endOffset)
          Create an Author content fragment containing a clone of the document content for the given range of offsets.
 AuthorDocumentFragment createNewDocumentFragmentInContext(java.lang.String xmlFragment, int contentOffset)
          Create a new AuthorDocumentFragment from an XML string in a specified context.
 AuthorDocumentFragment[] createNewDocumentFragmentsInContext(java.lang.String[] xmlFragments, int[] contentOffsets)
          Create an array of AuthorDocumentFragment from an array of XML strings in specified contexts.
 AuthorDocumentFragment createNewDocumentTextFragment(java.lang.String textFragment)
          Create a new AuthorDocumentFragment from an string.
 javax.swing.text.Position createPositionInContent(int offset)
          Create a flexible position in the Author Content.
 boolean delete(int startOffset, int endOffset)
          Deletes a document fragment between the start and end offset.
 boolean delete(int startOffset, int endOffset, boolean backspace)
          Deletes a document fragment between the start and end offset.
 boolean deleteNode(AuthorNode node)
          Delete a node.
 void endCompoundEdit()
          End a compound edit.
 java.lang.Object[] evaluateXPath(java.lang.String xpathExpression, AuthorNode contextNode, boolean ignoreTexts, boolean ignoreCData, boolean ignoreComments, boolean processChangeMarkers)
          Evaluates an XPath 2.0 expression.
 java.lang.Object[] evaluateXPath(java.lang.String xpathExpression, AuthorNode contextNode, boolean ignoreTexts, boolean ignoreCData, boolean ignoreComments, boolean processChangeMarkers, XPathVersion xpathVersion)
          Evaluates an XPath expression.
 java.lang.Object[] evaluateXPath(java.lang.String xpathExpression, boolean ignoreTexts, boolean ignoreCData, boolean ignoreComments)
          Evaluates an XPath 2.0 expression.
 java.lang.Object[] evaluateXPath(java.lang.String xpathExpression, boolean ignoreTexts, boolean ignoreCData, boolean ignoreComments, boolean processChangeMarkers)
          Evaluates an XPath 2.0 expression.
 AuthorNode[] findNodesByXPath(java.lang.String xpathExpression, AuthorNode contextNode, boolean ignoreTexts, boolean ignoreCData, boolean ignoreComments, boolean processChangeMarkers)
          Finds the author nodes selected by the given XPath 2.0 expression.
 AuthorNode[] findNodesByXPath(java.lang.String xpathExpression, AuthorNode contextNode, boolean ignoreTexts, boolean ignoreCData, boolean ignoreComments, boolean processChangeMarkers, XPathVersion xpathVersion)
          Finds the author nodes selected by the given XPath expression.
 AuthorNode[] findNodesByXPath(java.lang.String xpathExpression, boolean ignoreTexts, boolean ignoreCData, boolean ignoreComments)
          Finds the author nodes selected by the given XPath 2.0 expression.
 AuthorNode[] findNodesByXPath(java.lang.String xpathExpression, boolean ignoreTexts, boolean ignoreCData, boolean ignoreComments, boolean processChangeMarkers)
          Finds the author nodes selected by the given XPath 2.0 expression.
 AuthorDocument getAuthorDocumentNode()
          Returns the edited author document.
 AuthorSchemaManager getAuthorSchemaManager()
           
 void getChars(int where, int len, javax.swing.text.Segment chars)
          The content represents the entire text content of the Author page + additional markers/sentinels at offsets which are pointed to by the AuthorNodes.
 AuthorNode getCommonAncestor(AuthorNode[] nodes)
          Get the common parent for the nodes.
 AuthorNode getCommonParentNode(AuthorDocument doc, int startOffset, int endOffset)
          Find the common ancestor node of the two offsets.
 OffsetInformation getContentInformationAtOffset(int offset)
          Returns content information for the offset.
 AuthorDocumentType getDoctype()
          Returns information about the internal associated document type.
 AuthorDocumentFilter getDocumentFilter()
          Gets the AuthorDocumentFilter which is currently set for altering the document edits.
 AuthorFilteredContent getFilteredContent(int start, int end, AuthorNodesFilter nodesFilter)
          Retrieves the content between the given start and end offset, excluding the content of the invisible nodes (that have display none style property), the content deleted with track changes, the sentinels of inline elements and the content of filtered nodes.
 AuthorNode getNodeAtOffset(int offset)
          Returns the node at the given offset.
 java.util.List<AuthorNode> getNodesToSelect(int selectionStart, int selectionEnd)
          Compute the list with nodes to select when a selection is present in editor.
 java.lang.String getText(int offset, int length)
          Deprecated. Use the API based on the AuthorNode to get only the displayed text without mark-up markers.
 TextContentIterator getTextContentIterator(int startOffset, int endOffset)
          Get an iterator over the text content between two offsets.
 int getTextContentLength()
          Deprecated. Use the API based on the AuthorNode to get the length of the displayed text only, without mark-up markers.
 javax.swing.undo.UndoManager getUndoManager()
          Get access to the Author undo manager.
 UniqueAttributesProcessor getUniqueAttributesProcessor()
          Get the compound unique attributes processor which can be asked if a certain attribute should get copied on a split.
 java.lang.String getUnparsedEntityUri(AuthorNode contextNode, java.lang.String entityName)
          Returns the URI of the unparsed entity with the specified name, in the same document as the context node.
 java.lang.String getXPathExpression(int offset)
          Returns the XPath expression of the node identified by the given offset.
 int getXPathLocationOffset(java.lang.String xpathLocation, java.lang.String relativePosition)
          Compute the document offset defined by the XPath location and relative position.
 boolean inInlineContext(int offset)
          Test if the context at the given offset is inline(as defined in the CSS specs) or not.
 void insertFragment(int insertOffset, AuthorDocumentFragment frag)
          Insert an AuthorDocumentFragment at the given offset.
 SchemaAwareHandlerResult insertFragmentSchemaAware(int insertOffset, AuthorDocumentFragment frag)
          Insert an AuthorDocumentFragment at the given offset in schema aware mode.
 void insertMultipleElements(AuthorElement parentElement, java.lang.String[] elementNames, int[] offsets, java.lang.String namespace)
          Insert multiple elements at the given offsets.
 boolean insertMultipleFragments(AuthorElement parentElement, AuthorDocumentFragment[] fragments, int[] offsets)
          Insert multiple fragments at the given offsets.
 void insertText(int offset, java.lang.String text)
          Inserts a text at the given offset.
 void insertXMLFragment(java.lang.String xmlFragment, AuthorNode relativeTo, java.lang.String relativePosition)
          Insert an XML fragment relative to the given node and according with the relativePosition.
 void insertXMLFragment(java.lang.String xmlFragment, int offset)
          Insert an XML fragment at the given offset.
 void insertXMLFragment(java.lang.String xmlFragment, java.lang.String xpathLocation, java.lang.String relativePosition)
          Insert an XML fragment relative to the node identified by the xpathLocation and according with the relativePosition.
 SchemaAwareHandlerResult insertXMLFragmentSchemaAware(java.lang.String xmlFragment, int offset)
          Insert an XML fragment at the given offset in schema aware mode.
 SchemaAwareHandlerResult insertXMLFragmentSchemaAware(java.lang.String xmlFragment, int offset, boolean replaceSelection)
          Insert an XML fragment at the given offset in schema aware mode.
 SchemaAwareHandlerResult insertXMLFragmentSchemaAware(java.lang.String xmlFragment, java.lang.String xpathLocation, java.lang.String relativePosition)
          Insert an XML fragment relative to the node identified by the xpathLocation and according with the relativePosition.
 boolean isEditable(AuthorNode node)
          Test if a node is editable or not.
 void multipleDelete(AuthorElement parentElement, int[] startOffsets, int[] endOffsets)
          Deletes the given intervals.
 boolean processContentRange(int startOffset, int endOffset, RangeProcessor rangeProcessor)
          This method is useful if you want to make text processing on a given Author selection.
 void refreshNodeReferences(AuthorNode node)
          Refresh node references recursively.
 void removeAttribute(java.lang.String attributeName, AuthorElement element)
          Removes an attribute from the given element.
 void removeAuthorListener(AuthorListener listener)
          Remove an Author listener.
 void removeAuthorPersistentHighlightListener(AuthorPersistentHighlightsListener listener)
          Removes a persistent highlights listener.
 void removeClipboardFragmentProcessor(ClipboardFragmentProcessor clipboardFragmentProcessor)
          Remove a processor which can analyze and modify AuthorDocumentFragment objects before they are inserted in the Author.
 void removePseudoClass(java.lang.String pseudoClass, AuthorElement element)
          Removes a pseudo class from the given element.
 void removeUniqueAttributesProcessor(UniqueAttributesProcessor uniqueAttributesProcessor)
          Remove a processor which is asked to automatically generate unique IDs after content has been inserted in the Author.
 void renameElement(AuthorElement contextNode, java.lang.String newName)
          Rename an Author Element, set another qualified name to it.
 void replaceRoot(AuthorDocumentFragment fragment)
          Replace the current root element with the new given one.
 java.lang.String serializeFragmentToXML(AuthorDocumentFragment fragment)
          Takes the given fragment and serializes it to XML text in the context of the current document.
 void setAttribute(java.lang.String attributeName, AttrValue value, AuthorElement element)
          Sets the value of an attribute in the specified element.
 void setDoctype(AuthorDocumentType docType)
          Set a new internal document type to the Author content.
 void setDocumentFilter(AuthorDocumentFilter authorDocumentFilter)
          Sets the AuthorDocumentFilter to be used for altering the document edits.
 void setMultipleAttributes(int parentElementStartOffset, int[] elementOffsets, java.util.Map<java.lang.String,AttrValue> attributes)
          Sets the value of the given attribute in the specified elements.
 void setPseudoClass(java.lang.String pseudoClass, AuthorElement element)
          Sets a pseudo class in the specified element.
 void setRenderingInfoChangedListener(RenderingInfoChangedListener listener)
          Sets the listener to be notified when the rendering info of a node has changed.
 void surroundInFragment(AuthorDocumentFragment xmlFragment, int startOffset, int endOffset)
          Surround the content between the given offsets with the xmlFragment.
 void surroundInFragment(java.lang.String xmlFragment, int startOffset, int endOffset)
          Surround the content between the given offsets with the xmlFragment.
 void surroundInText(java.lang.String header, java.lang.String footer, int startOffset, int endOffset)
          Surround the content between the given offsets with plain text fragments(without XML parsing).
 AuthorDocumentFragment unwrapDocumentFragment(AuthorDocumentFragment fragmentToUnwrap)
          Unwrap a given Author document fragment.
 

Method Detail

delete

boolean delete(int startOffset,
               int endOffset)
Deletes a document fragment between the start and end offset.
The author content contains the entire XML document text and special marker characters. Each author node points in the content to the start and end marker characters which are used to delimit it's range. The start and end offsets pointed to by the AuthorNode can be retrieved using the AuthorNode.getStartOffset() and AuthorNode.getEndOffset()

The image represents part of the document content and red markers represent special control characters which represent the node ranges.

Parameters:
startOffset - Start offset, 0 based, inclusive.
endOffset - End offset, 0 based, inclusive.
Returns:
true if the delete operation was successful.

delete

boolean delete(int startOffset,
               int endOffset,
               boolean backspace)
Deletes a document fragment between the start and end offset.
The author content contains the entire XML document text and special marker characters. Each author node points in the content to the start and end marker characters which are used to delimit it's range. The start and end offsets pointed to by the AuthorNode can be retrieved using the AuthorNode.getStartOffset() and AuthorNode.getEndOffset()

The image represents part of the document content and red markers represent special control characters which represent the node ranges.

Parameters:
startOffset - Start offset, 0 based, inclusive.
endOffset - End offset, 0 based, inclusive.
backspace - true if delete operation was triggered by the user pressing the backspace key.
Returns:
true if the delete operation was successful.

deleteNode

boolean deleteNode(AuthorNode node)
Delete a node.

Parameters:
node - The AuthorNode to delete.
Returns:
true if the delete node operation was successful.

replaceRoot

void replaceRoot(AuthorDocumentFragment fragment)
Replace the current root element with the new given one. The fragment must contain only one element, otherwise the replacement will not be performed.

Parameters:
fragment - The document fragment containing the new root element.

createDocumentFragment

AuthorDocumentFragment createDocumentFragment(int startOffset,
                                              int endOffset)
                                              throws javax.swing.text.BadLocationException
Create an Author content fragment containing a clone of the document content for the given range of offsets.
The offset ranges must be from the current AuthorDocument.

The Author content contains the entire XML document text and special marker characters. Each author node points in the content to the start and end marker characters which are used to delimit it's range. The start and end offsets pointed to by the AuthorNode can be retrieved using the AuthorNode.getStartOffset() and AuthorNode.getEndOffset()

The image represents part of the document content and red markers represent special control characters which represent the node ranges.

Parameters:
startOffset - The start offset, 0 based, inclusive.
endOffset - The end offset, 0 based, inclusive.
Returns:
A new AuthorDocumentFragment. It does not return a null fragment.
Throws:
javax.swing.text.BadLocationException - When the offsets are not between 0 and the content length, or the startOffset is greater than the endOffset.

createNewDocumentFragmentInContext

AuthorDocumentFragment createNewDocumentFragmentInContext(java.lang.String xmlFragment,
                                                          int contentOffset)
                                                          throws AuthorOperationException
Create a new AuthorDocumentFragment from an XML string in a specified context.
The author content contains the entire XML document text and special marker characters. Each author node points in the content to the start and end marker characters which are used to delimit it's range. The start and end offsets pointed to by the AuthorNode can be retrieved using the AuthorNode.getStartOffset() and AuthorNode.getEndOffset()

The image represents part of the document content and red markers represent special control characters which represent the node ranges.

Parameters:
xmlFragment - The XML Fragment.
contentOffset - The offset where the XML fragment should be inserted. This method doesn't perform any insertion. This parameter is used to resolve entities and default attribute values from the DTD in the specified XML fragment.
Returns:
The newly created AuthorDocumentFragment. It does not return a null fragment.
Throws:
AuthorOperationException - If the new fragment creation fails.

createNewDocumentFragmentsInContext

AuthorDocumentFragment[] createNewDocumentFragmentsInContext(java.lang.String[] xmlFragments,
                                                             int[] contentOffsets)
                                                             throws AuthorOperationException
Create an array of AuthorDocumentFragment from an array of XML strings in specified contexts.
This method should be used when multiple Author document fragments must be created. In this situation the fragments are created faster than creating each of them by calling createNewDocumentFragmentInContext(String, int) method.

The author content contains the entire XML document text and special marker characters. Each author node points in the content to the start and end marker characters which are used to delimit it's range. The start and end offsets pointed to by the AuthorNode can be retrieved using the AuthorNode.getStartOffset() and AuthorNode.getEndOffset()

The image represents part of the document content and red markers represent special control characters which represent the node ranges.

Parameters:
xmlFragments - The array of XML fragments.
contentOffsets - The offsets where the XML fragments should be inserted. The xml fragments and context offsets arrays must have the same size. The nth offset corresponds to the nth xml fragment.
Returns:
The newly created AuthorDocumentFragment. It does not return a null fragment.
Throws:
AuthorOperationException - If the xml fragments and context offsets sizes are different or a fragment creation fails.
Since:
14

createNewDocumentTextFragment

AuthorDocumentFragment createNewDocumentTextFragment(java.lang.String textFragment)
                                                     throws AuthorOperationException
Create a new AuthorDocumentFragment from an string. The returned fragment will contain only a text node and if the text fragment contains mark-up, it will be escaped. If the text has mark-up and you actually want to create author nodes from it then you should use createNewDocumentFragmentInContext(String, int).

Parameters:
textFragment - The text fragment.
Returns:
The newly created AuthorDocumentFragment holding the text node. If the text fragment contains mark-up, it will be escaped. It does not return a null fragment.
Throws:
AuthorOperationException - If the new fragment creation fails.

serializeFragmentToXML

java.lang.String serializeFragmentToXML(AuthorDocumentFragment fragment)
                                        throws javax.swing.text.BadLocationException
Takes the given fragment and serializes it to XML text in the context of the current document. The following code example extracts the selection as an XML fragment, processes and then reinserts it:


 if(authorAccess.getEditorAccess().hasSelection()) {
    AuthorDocumentController documentController = authorAccess.getDocumentController();
    AuthorDocumentFragment selectionAsAFragment = documentController.createDocumentFragment(
         authorAccess.getEditorAccess().getSelectionStart(), authorAccess.getEditorAccess().getSelectionEnd());
    String selectionAsXML = documentController.serializeFragmentToXML(selectionAsAFragment);
    
    //Deletes the selection
    authorAccess.getEditorAccess().deleteSelection();
    
    //Process the selectionAsXML fragment, modify it.
    //................
    
    //Insert the XML fragment back at caret position.
    documentController.insertXMLFragment(selectionAsXML, authorAccess.getEditorAccess().getCaretOffset());
 }
 

If the fragment contains change tracking highlights, they will be serialized as processing instructions.

Parameters:
fragment - The AuthorDocumentFragment to serialize.
Returns:
An equivalent String representation of the given fragment. It does not return a null String. If the fragment cannot be serialized it will return an empty String.
Throws:
javax.swing.text.BadLocationException - If the serialization could not be accomplished, usually because the fragment was not properly built.

setAttribute

void setAttribute(java.lang.String attributeName,
                  AttrValue value,
                  AuthorElement element)
Sets the value of an attribute in the specified element. Attributes set in this manner (as opposed to calling AuthorElement.setAttribute(String, AttrValue) directly) will be subject to undo/redo.

Parameters:
attributeName - Name of the attribute being changed.
value - New AttrValue for the attribute. If null, the attribute is removed from the element.
element - The AuthorElement whose attribute is changing.

setMultipleAttributes

void setMultipleAttributes(int parentElementStartOffset,
                           int[] elementOffsets,
                           java.util.Map<java.lang.String,AttrValue> attributes)
Sets the value of the given attribute in the specified elements. Attributes set in this manner will be subject to undo/redo.

Parameters:
parentElementStartOffset - The start offset of the parent element.
elementOffsets - The start offset for each element.
attributes - The list with attributes. Every attribute name is mapped to an AttrValue object. If the value is null, the attribute will be removed.
Since:
16

*********************************
EXPERIMENTAL - Subject to change
********************************

Please note that this API is not marked as final and it can change in one of the next versions of the application. If you have suggestions, comments about it, please let us know.


removeAttribute

void removeAttribute(java.lang.String attributeName,
                     AuthorElement element)
Removes an attribute from the given element. Attributes removed in this manner (as opposed to calling AuthorElement.setAttribute(String, AttrValue) directly) will be subject to undo/redo.

Parameters:
attributeName - Name of the attribute to remove.
element - The AuthorElement whose attribute will be removed.

setPseudoClass

void setPseudoClass(java.lang.String pseudoClass,
                    AuthorElement element)

Sets a pseudo class in the specified element.

This change in not subject to undo/redo.

What is good for: You can use a non standard (custom) pseudo class to impose a style change on a specific element. For instance you can have CSS styles matching a custom pseudo-class, like the one below:

   section:access-control-user {
      display:block;
   } 
   section {
      display:none;
   } 
 

By setting the pseudoClass "access-control-user", the element section will become visible.

Another example:

   *:caret-visited {
      color:red;
   } 
 
You could create an AuthorCaretListener that sets the caret-visited pseudo class to the element at the caret location. The effect will be that all the elements traversed by the caret become red.

Parameters:
pseudoClass - Name of the pseudo class being set.
element - The AuthorElement whose attribute is changing.
Since:
15.2

removePseudoClass

void removePseudoClass(java.lang.String pseudoClass,
                       AuthorElement element)
Removes a pseudo class from the given element. This change in not subject to undo/redo.

Parameters:
pseudoClass - Name of the pseudo class being set.
element - The AuthorElement whose attribute will be removed.
Since:
15.2

getNodeAtOffset

AuthorNode getNodeAtOffset(int offset)
                           throws javax.swing.text.BadLocationException
Returns the node at the given offset. The given offset must be greater or equal to 0 and less than the current document length.

Note: If the caret has the offset of an element's start offset marker character, it is considered to be before the element.
If the caret has the offset of an element's end offset marker character, it is considered to be inside the element.

The author content contains the entire XML document text and special marker characters. Each author node points in the content to the start and end marker characters which are used to delimit it's range. The start and end offsets pointed to by the AuthorNode can be retrieved using the AuthorNode.getStartOffset() and AuthorNode.getEndOffset()

The image represents part of the document content and red markers represent special control characters which represent the node ranges.

Parameters:
offset - The offset in the content, zero based.
Returns:
The AuthorNode containing the offset, or null when the actual document is null.
Throws:
javax.swing.text.BadLocationException - When the offset is negative or greater than the content length.

getContentInformationAtOffset

OffsetInformation getContentInformationAtOffset(int offset)
                                                throws javax.swing.text.BadLocationException
Returns content information for the offset. If the offset is on a marker character the returned result will also contain the node which contains the range indicated by the marker.

Parameters:
offset - The offset in the content, zero based.
Returns:
content information for the offset.

The author content contains the entire XML document text and special marker characters. Each author node points in the content to the start and end marker characters which are used to delimit it's range. The start and end offsets pointed to by the AuthorNode can be retrieved using the AuthorNode.getStartOffset() and AuthorNode.getEndOffset() The image represents part of the document content and red markers represent special control characters which represent the node ranges.
Throws:
javax.swing.text.BadLocationException
Since:
12.2

createDocumentFragment

AuthorDocumentFragment createDocumentFragment(AuthorNode node,
                                              boolean copyContent)
                                              throws javax.swing.text.BadLocationException
Create a document fragment containing a copy of the node. The node must be from the current AuthorDocument. The attributes of the elements will be copied. If copyContent is true the node content will be copied also.

Parameters:
node - The AuthorNode to be duplicated.
copyContent - If true the content of the node will also be duplicated.
Returns:
The AuthorDocumentFragment containing the duplicated node. It does not return a null fragment.
Throws:
javax.swing.text.BadLocationException - When the operation fails.

getText

@Deprecated
java.lang.String getText(int offset,
                                    int length)
                         throws javax.swing.text.BadLocationException
Deprecated. Use the API based on the AuthorNode to get only the displayed text without mark-up markers.

Gets a sequence of text from the document text content. The document text content can be obtained by adding all the text nodes content.
The offset is considered to be relative to the text content start offset. So the 0 offset corresponds to the offset of the first valid char in the document.
The length represents also a number of valid chars encountered after the real start offset was determined.

For the document:
[?PI?][article][!COMMENT][para]PARAGRAPH[/para][/article]

getText(0, 18) returns "PICOMMENTPARAGRAPH"
getText(5, 8) returns "MENTPARA"

Parameters:
offset - The starting offset >= 0.
length - The number of characters to retrieve >= 0
Returns:
The text
Throws:
javax.swing.text.BadLocationException - The range given includes a position that is not a valid position within the document text content.

getTextContentLength

@Deprecated
int getTextContentLength()
                         throws javax.swing.text.BadLocationException
Deprecated. Use the API based on the AuthorNode to get the length of the displayed text only, without mark-up markers.

Returns the length of the text content of the document. This is the number of valid characters in the document text. The length can be determined by the adding all text nodes content length.

For the document:
[?PI?][article][!COMMENT][para]PARAGRAPH[/para][/article]
The text content length will be:
"PI".length() + "COMMENT".length() + "PARAGRAPH".length()
2 + 7 + 9 = 18

Returns:
The text content length >= 0
Throws:
javax.swing.text.BadLocationException

getUndoManager

javax.swing.undo.UndoManager getUndoManager()
Get access to the Author undo manager.

Returns:
The Author undo manager. The returned undo manager cannot be null.

beginCompoundEdit

void beginCompoundEdit()
Begin a compound edit. This method should be called to signal to the editing support that a complex editing operation begins. The editing operations that occur between beginCompoundEdit() and endCompoundEdit() methods calls are regarded by the UndoManager as a single operation which can be undone/redone in one step.


endCompoundEdit

void endCompoundEdit()
End a compound edit. This method should be called to signal to the editing support that a complex editing operation ends.

See Also:
beginCompoundEdit()

cancelCompoundEdit

void cancelCompoundEdit()
Cancel the current compound edit. This method should be called to signal to the editing support that all edits performed so far inside a current compound edit must be undone. The editing operations that occurred after the previous call to beginCompoundEdit() will be undo by the UndoManager. Note that the compound edit does not end after a call to this method, so an explicit call to endCompoundEdit() is required.

See Also:
beginCompoundEdit(), endCompoundEdit()

insertText

void insertText(int offset,
                java.lang.String text)
Inserts a text at the given offset. After the operation the caret will be positioned at the end of the inserted text.
The author content contains the entire XML document text and special marker characters. Each author node points in the content to the start and end marker characters which are used to delimit it's range. The start and end offsets pointed to by the AuthorNode can be retrieved using the AuthorNode.getStartOffset() and AuthorNode.getEndOffset()

The image represents part of the document content and red markers represent special control characters which represent the node ranges.

Parameters:
offset - The insert position, 0 based.
text - The text to be inserted.

insertXMLFragment

void insertXMLFragment(java.lang.String xmlFragment,
                       int offset)
                       throws AuthorOperationException
Insert an XML fragment at the given offset. After the operation the caret will be positioned in the first leaf of the fragment.
The author content contains the entire XML document text and special marker characters. Each author node points in the content to the start and end marker characters which are used to delimit it's range. The start and end offsets pointed to by the AuthorNode can be retrieved using the AuthorNode.getStartOffset() and AuthorNode.getEndOffset()

The image represents part of the document content and red markers represent special control characters which represent the node ranges.

Parameters:
xmlFragment - The XML fragment to insert.
offset - The insert position, 0 based.
Throws:
AuthorOperationException - If the fragment could not be inserted.

insertXMLFragment

void insertXMLFragment(java.lang.String xmlFragment,
                       java.lang.String xpathLocation,
                       java.lang.String relativePosition)
                       throws AuthorOperationException
Insert an XML fragment relative to the node identified by the xpathLocation and according with the relativePosition. Note: if the xpathLocation is not specified then the XML fragment will be inserted at caret position and the relativePosition will be ignored.

After the operation the caret will be positioned in the first leaf of the fragment.

Parameters:
xmlFragment - The XML fragment.
xpathLocation - The XPath location.
relativePosition - The position relative to the node identified by the XPath location. Can be one of the constants: AuthorConstants.POSITION_BEFORE, AuthorConstants.POSITION_AFTER, AuthorConstants.POSITION_INSIDE_FIRST or AuthorConstants.POSITION_INSIDE_LAST.
Throws:
AuthorOperationException - If the fragment could not be inserted.

insertXMLFragment

void insertXMLFragment(java.lang.String xmlFragment,
                       AuthorNode relativeTo,
                       java.lang.String relativePosition)
                       throws AuthorOperationException
Insert an XML fragment relative to the given node and according with the relativePosition.

After the operation the caret will be positioned at the end of the inserted XML fragment.

Parameters:
xmlFragment - The XML fragment.
relativeTo - The node to insert fragment relative to.
relativePosition - The position relative to the node. Can be one of the constants: AuthorConstants.POSITION_BEFORE, AuthorConstants.POSITION_AFTER, AuthorConstants.POSITION_INSIDE_FIRST or AuthorConstants.POSITION_INSIDE_LAST.
Throws:
AuthorOperationException - If the fragment could not be inserted.

insertXMLFragmentSchemaAware

SchemaAwareHandlerResult insertXMLFragmentSchemaAware(java.lang.String xmlFragment,
                                                      int offset)
                                                      throws AuthorOperationException
Insert an XML fragment at the given offset in schema aware mode. A normal insertion is executed when no schema is specified or schema aware feature is disable by the user (see Preferences / Editor / Pages / Author / Schema aware). If the fragments insertion is not allowed, a dialog will be shown proposing one of following solutions if they apply:

If the developer specifies an AuthorSchemaAwareEditingHandler then this handler has priority for executing the insert operation.

Parameters:
xmlFragment - The XML fragment to insert.
offset - The insert position, 0 based.
Returns:
The result of the schema aware insertion. Can be used to get the insertion offset for the given fragments.
Throws:
AuthorOperationException - If the fragment could not be inserted.

insertXMLFragmentSchemaAware

SchemaAwareHandlerResult insertXMLFragmentSchemaAware(java.lang.String xmlFragment,
                                                      int offset,
                                                      boolean replaceSelection)
                                                      throws AuthorOperationException
Insert an XML fragment at the given offset in schema aware mode. A normal insertion is executed when no schema is specified or schema aware feature is disable by the user (see Preferences / Editor / Pages / Author / Schema aware). If the fragments insertion is not allowed, a dialog will be shown proposing one of following solutions if they apply:

If the developer specifies an AuthorSchemaAwareEditingHandler then this handler has priority for executing the insert operation.

Parameters:
xmlFragment - The XML fragment to insert.
offset - The insert position, 0 based.
replaceSelection - true to replace the selected Author content with the fragment, false to leave the selected content and paste at caret position.
Returns:
The result of the schema aware insertion. Can be used to get the insertion offset for the given fragments.
Throws:
AuthorOperationException - If the fragment could not be inserted.

insertFragment

void insertFragment(int insertOffset,
                    AuthorDocumentFragment frag)
Insert an AuthorDocumentFragment at the given offset.
The author content contains the entire XML document text and special marker characters. Each author node points in the content to the start and end marker characters which are used to delimit it's range. The start and end offsets pointed to by the AuthorNode can be retrieved using the AuthorNode.getStartOffset() and AuthorNode.getEndOffset()

The image represents part of the document content and red markers represent special control characters which represent the node ranges.

Parameters:
insertOffset - The offset where the fragment will be inserted, 0 based.
frag - The AuthorDocumentFragment to be inserted.

processContentRange

boolean processContentRange(int startOffset,
                            int endOffset,
                            RangeProcessor rangeProcessor)
                            throws javax.swing.text.BadLocationException,
                                   AuthorOperationException
This method is useful if you want to make text processing on a given Author selection. You will receive a call back which will give you the AuthorDocumentFragment to process. When finished, the range will be replaced with the processed fragment.

The author content contains the entire XML document text and special marker characters. Each author node points in the content to the start and end marker characters which are used to delimit it's range.

The start and end offsets pointed to by the AuthorNode can be retrieved using the AuthorNode.getStartOffset() and AuthorNode.getEndOffset().


The image represents part of the document content and red markers represent special control characters which represent the node ranges.

Parameters:
startOffset - Start offset of the processed range (inclusive).
endOffset - End offset of the processed range (inclusive).
rangeProcessor - The range processor which gets notified to process the AuthorDocumentFragment.
Returns:
true if the modifications were merged back in the Author content. For example when the selection cannot be replaced (inside a not-editable element) this method can return false.
Throws:
javax.swing.text.BadLocationException
AuthorOperationException
Since:
12.2

insertFragmentSchemaAware

SchemaAwareHandlerResult insertFragmentSchemaAware(int insertOffset,
                                                   AuthorDocumentFragment frag)
                                                   throws AuthorOperationException
Insert an AuthorDocumentFragment at the given offset in schema aware mode. A normal insertion is executed when no schema is specified or schema aware feature is disable by the user (see Preferences / Editor / Pages / Author / Schema aware).

For more details about schema aware solutions see comments from insertXMLFragmentSchemaAware(String, int) method.


The author content contains the entire XML document text and special marker characters. Each author node points in the content to the start and end marker characters which are used to delimit it's range. The start and end offsets pointed to by the AuthorNode can be retrieved using the AuthorNode.getStartOffset() and AuthorNode.getEndOffset()

The image represents part of the document content and red markers represent special control characters which represent the node ranges.

Parameters:
insertOffset - The offset where the fragment will be inserted, 0 based.
frag - The AuthorDocumentFragment to be inserted.
Returns:
The result of the schema aware insertion.
Throws:
AuthorOperationException - If the fragment could not be inserted.

surroundInFragment

void surroundInFragment(java.lang.String xmlFragment,
                        int startOffset,
                        int endOffset)
                        throws AuthorOperationException
Surround the content between the given offsets with the xmlFragment. If endOffset < startOffset the xmlFragment will be inserted at startOffset.
The author content contains the entire XML document text and special marker characters. Each author node points in the content to the start and end marker characters which are used to delimit it's range. The start and end offsets pointed to by the AuthorNode can be retrieved using the AuthorNode.getStartOffset() and AuthorNode.getEndOffset()

The image represents part of the document content and red markers represent special control characters which represent the node ranges.

Parameters:
xmlFragment - The XML fragment which will surround the given interval. The first leaf node of the XML fragment will be the parent of the surrounded content.
startOffset - The start offset of the content to be surrounded, 0 based and inclusive.
endOffset - The end offset of the content to be surrounded, 0 based and inclusive.
Throws:
AuthorOperationException - If the content between start and end offset could not be surrounded.

surroundInFragment

void surroundInFragment(AuthorDocumentFragment xmlFragment,
                        int startOffset,
                        int endOffset)
                        throws AuthorOperationException
Surround the content between the given offsets with the xmlFragment. If endOffset < startOffset the xmlFragment will be inserted at startOffset.
The author content contains the entire XML document text and special marker characters. Each author node points in the content to the start and end marker characters which are used to delimit it's range. The start and end offsets pointed to by the AuthorNode can be retrieved using the AuthorNode.getStartOffset() and AuthorNode.getEndOffset()

The image represents part of the document content and red markers represent special control characters which represent the node ranges.

Parameters:
xmlFragment - The XML fragment which will surround the given interval. The first leaf node of the XML fragment will be the parent of the surrounded content.
startOffset - The start offset of the content to be surrounded, 0 based and inclusive.
endOffset - The end offset of the content to be surrounded, 0 based and inclusive.
Throws:
AuthorOperationException - If the content between start and end offset could not be surrounded.
Since:
12.1

surroundInText

void surroundInText(java.lang.String header,
                    java.lang.String footer,
                    int startOffset,
                    int endOffset)
                    throws AuthorOperationException
Surround the content between the given offsets with plain text fragments(without XML parsing). The method inserts the header at startOffset and the footer at endOffset.
The author content contains the entire XML document text and special marker characters. Each author node points in the content to the start and end marker characters which are used to delimit it's range. The start and end offsets pointed to by the AuthorNode can be retrieved using the AuthorNode.getStartOffset() and AuthorNode.getEndOffset()

The image represents part of the document content and red markers represent special control characters which represent the node ranges.

Parameters:
header - The header to be inserted before the surrounded text.
footer - The footer to be inserted after the surrounded text.
startOffset - The start offset of the text to be surrounded, 0 based.
endOffset - The end offset of the text to be surrounded, 0 based.
Throws:
AuthorOperationException - If the operation failed.

inInlineContext

boolean inInlineContext(int offset)
                        throws javax.swing.text.BadLocationException,
                               AuthorOperationException
Test if the context at the given offset is inline(as defined in the CSS specs) or not.

The CSS display property is taken into account when determining this state.

For example a text paragraph determines an inline context, and for an offset inside this paragraph the method will return true. For an offset between two paragraphs (considered to be block level) the method will return false.

Parameters:
offset - The offset in the document, zero based.
Returns:
Returns true if the given offset is inside an inline context. false otherwise.
Throws:
javax.swing.text.BadLocationException - When the offset does not exists in the document content.
AuthorOperationException - If the operation failed.

addAuthorListener

void addAuthorListener(AuthorListener listener)
Add an Author listener to be notified about changes regarding the document and the document structure.

Parameters:
listener - The AuthorListener to be added.

addAuthorPersistentHighlightListener

void addAuthorPersistentHighlightListener(AuthorPersistentHighlightsListener listener)
Adds a listener to be notified about changes regarding the persistent highlights. In the persistent highlights are included:

Parameters:
listener - The listener
Since:
14
See Also:
AuthorPersistentHighlight.PersistentHighlightType, AuthorPersistentHighlight

removeAuthorPersistentHighlightListener

void removeAuthorPersistentHighlightListener(AuthorPersistentHighlightsListener listener)
Removes a persistent highlights listener.

Parameters:
listener - The listener to remove.
Since:
14

addPersistentHighlightsFilter

void addPersistentHighlightsFilter(AuthorPersistentHighlightsFilter persistentHighlightsFilter)
Add a persistent highlights filter. A filter capable of filtering the highlights by author is present by default.

Parameters:
persistentHighlightsFilter - The filter to be added.
Since:
15

removeAuthorListener

void removeAuthorListener(AuthorListener listener)
Remove an Author listener.

Parameters:
listener - The AuthorListener to be removed.

evaluateXPath

java.lang.Object[] evaluateXPath(java.lang.String xpathExpression,
                                 boolean ignoreTexts,
                                 boolean ignoreCData,
                                 boolean ignoreComments,
                                 boolean processChangeMarkers)
                                 throws AuthorOperationException
Evaluates an XPath 2.0 expression. This function returns the result of the given XPath expression as an array of Object. Author DOM text nodes, DOM CDATA sections and DOM comment wrappers can be ignored for performance reasons.
For example, executing the expression:
//node()
will return an array with all the Author DOM Node wrappers in the document.
while evaluating the expression:
count(//node())
will return an array having a single component representing the number of nodes in the document.
Evaluating the expression:
//node(), count(//node())
will return an array containing all the Author DOM Node wrappers in the document and having as last component the total number of nodes.

You can also use the XPath extension functions oxy:current-selected-element() and oxy:allows-child-element().

Parameters:
xpathExpression - The XPath expression. If the XPath expression is relative, it will be computed in the context of the current caret position.
ignoreTexts - If true DOM text nodes will not be returned.
ignoreCData - If true DOM CDATA sections will not be returned.
ignoreComments - If true DOM comments will not be returned.
processChangeMarkers - If false the change markers (inserts/deletes/comments) will be ignored and the XPath will return results as if the insert changes are accepted, the delete changes are rejected and the comment changes are ignored. If true the XPath will be applied over the document as if the change markers are applied. (All changes processed to processing instructions like when the XML document gets saved on disk).
Returns:
An array of objects representing the XPath result. It does not return a null array. If the XPath evaluation fails it will return an empty array.
Throws:
AuthorOperationException - If the XPath expression failed to be evaluated.

evaluateXPath

java.lang.Object[] evaluateXPath(java.lang.String xpathExpression,
                                 AuthorNode contextNode,
                                 boolean ignoreTexts,
                                 boolean ignoreCData,
                                 boolean ignoreComments,
                                 boolean processChangeMarkers,
                                 XPathVersion xpathVersion)
                                 throws AuthorOperationException
Evaluates an XPath expression. This function returns the result of the given XPath expression as an array of Object. Author DOM text nodes, DOM CDATA sections and DOM comment wrappers can be ignored for performance reasons.
For example, executing the expression:
//node()
will return an array with all the Author DOM Node wrappers in the document.
while evaluating the expression:
count(//node())
will return an array having a single component representing the number of nodes in the document.
Evaluating the expression:
//node(), count(//node())
will return an array containing all the Author DOM Node wrappers in the document and having as last component the total number of nodes.

You can also use the XPath extension functions oxy:current-selected-element() and oxy:allows-child-element().

Parameters:
xpathExpression - The XPath expression. If the XPath expression is relative, it will be computed in the context of the current caret position.
contextNode - The node in the context of which the relative XPath Expressions will computed. If null the context node will be the node at the current caret position.
ignoreTexts - If true DOM text nodes will not be returned.
ignoreCData - If true DOM CDATA sections will not be returned.
ignoreComments - If true DOM comments will not be returned.
processChangeMarkers - If false the change markers (inserts/deletes/comments) will be ignored and the XPath will return results as if the insert changes are accepted, the delete changes are rejected and the comment changes are ignored. If true the XPath will be applied over the document as if the change markers are applied. (All changes processed to processing instructions like when the XML document gets saved on disk).
xpathVersion - Used version of XPath.
Returns:
An array of objects representing the XPath result. It does not return a null array. If the XPath evaluation fails it will return an empty array.
Throws:
AuthorOperationException - If the XPath expression failed to be evaluated.
Since:
15

evaluateXPath

java.lang.Object[] evaluateXPath(java.lang.String xpathExpression,
                                 boolean ignoreTexts,
                                 boolean ignoreCData,
                                 boolean ignoreComments)
                                 throws AuthorOperationException
Evaluates an XPath 2.0 expression. This function returns the result of the given XPath expression as an array of Object. Author DOM text nodes, DOM CDATA sections and DOM comment wrappers can be ignored for performance reasons.
For example, executing the expression:
//node()
will return an array with all the Author DOM Node wrappers in the document.
while evaluating the expression:
count(//node())
will return an array having a single component representing the number of nodes in the document.
Evaluating the expression:
//node(), count(//node())
will return an array containing all the Author DOM Node wrappers in the document and having as last component the total number of nodes. If change tracking (insert/remove/comment) markers exist in the document they will be ignored and the XPath will return results as if the insert changes are accepted, the delete changes are rejected and the comment changes are ignored.

You can also use the XPath extension functions oxy:current-selected-element() and oxy:allows-child-element().

Parameters:
xpathExpression - The XPath expression. If the XPath expression is relative, it will be computed in the context of the current caret position.
ignoreTexts - If true DOM text nodes will not be returned.
ignoreCData - If true DOM CDATA sections will not be returned.
ignoreComments - If true DOM comments will not be returned.
Returns:
An array of objects representing the XPath result. It does not return a null array. If the XPath evaluation fails it will return an empty array.
Throws:
AuthorOperationException - If the XPath expression failed to be evaluated.

findNodesByXPath

AuthorNode[] findNodesByXPath(java.lang.String xpathExpression,
                              boolean ignoreTexts,
                              boolean ignoreCData,
                              boolean ignoreComments,
                              boolean processChangeMarkers)
                              throws AuthorOperationException
Finds the author nodes selected by the given XPath 2.0 expression. The result of this function is an array of AuthorNode selected by the given XPath expression. Author text nodes, Author CDATA section nodes and Author comment nodes can be ignored for performance reasons.
For example executing the expression:
//node()
will return an array with all the AuthorNode's in the document.
But the result of calling the function with the expression:
count(//node())
will return an empty array. If change tracking (insert/remove/comment) markers exist in the document they will be ignored and the XPath will return results as if the insert changes are accepted, the delete changes are rejected and the comment changes are ignored.

Parameters:
xpathExpression - The XPath expression.
ignoreTexts - If true Author text nodes will not be returned.
ignoreCData - If true Author CDATA sections will not be returned.
ignoreComments - If true Author comments will not be returned.
processChangeMarkers - If false the change markers (inserts/deletes/comments) will be ignored and the XPath will return results as if the insert changes are accepted, the delete changes are rejected and the comment changes are ignored. If true the XPath will be applied over the document as if the change markers are applied. (All changes processed to processing instructions like when the XML document gets saved on disk).
Returns:
The Author nodes selected by the XPath expression. It does not return a null array of nodes. If the evaluation of the XPath expression fails it will return an empty array.
Throws:
AuthorOperationException - If the XPath expression failed to be evaluated.

findNodesByXPath

AuthorNode[] findNodesByXPath(java.lang.String xpathExpression,
                              boolean ignoreTexts,
                              boolean ignoreCData,
                              boolean ignoreComments)
                              throws AuthorOperationException
Finds the author nodes selected by the given XPath 2.0 expression. The result of this function is an array of AuthorNode selected by the given XPath expression. Author text nodes, Author CDATA section nodes and Author comment nodes can be ignored for performance reasons.
For example executing the expression:
//node()
will return an array with all the AuthorNode's in the document.
But the result of calling the function with the expression:
count(//node())
will return an empty array. If change tracking (insert/remove/comment) markers exist in the document the XPath will be applied over the document as if the change tracking is applied (All changes processed to processing instructions like when the XML document gets saved on disk).

Parameters:
xpathExpression - The XPath expression. If the XPath expression is relative, it will be computed in the context of the current caret position.
ignoreTexts - If true Author text nodes will not be returned.
ignoreCData - If true Author CDATA sections will not be returned.
ignoreComments - If true Author comments will not be returned.
Returns:
The Author nodes selected by the XPath expression. It does not return a null array of nodes. If the evaluation of the XPath expression fails it will return an empty array.
Throws:
AuthorOperationException - If the XPath expression failed to be evaluated.

getXPathLocationOffset

int getXPathLocationOffset(java.lang.String xpathLocation,
                           java.lang.String relativePosition)
                           throws AuthorOperationException
Compute the document offset defined by the XPath location and relative position.

Parameters:
xpathLocation - The XPath defining a node in document.
relativePosition - The relative position to the node. One of the following: AuthorConstants.POSITION_BEFORE, AuthorConstants.POSITION_INSIDE_FIRST, AuthorConstants.POSITION_INSIDE_LAST or AuthorConstants.POSITION_AFTER
Returns:
The offset in document.
Throws:
AuthorOperationException - If it fails.

insertMultipleElements

void insertMultipleElements(AuthorElement parentElement,
                            java.lang.String[] elementNames,
                            int[] offsets,
                            java.lang.String namespace)
Insert multiple elements at the given offsets.
Note: The offsets and fragments must be in document order. The offset must be given in the original document, before any insertion occurs.

To insert two elements one after another:

          String[] fragments = new String[] {"elem1", "elem2"};
          insertMultipleElements(parentElement, fragments, new int[] {offset, offset}, null);
 
The result of running the above code will be:
   parent
     elem1
     elem2
 


The author content contains the entire XML document text and special marker characters. Each author node points in the content to the start and end marker characters which are used to delimit it's range. The start and end offsets pointed to by the AuthorNode can be retrieved using the AuthorNode.getStartOffset() and AuthorNode.getEndOffset()

The image represents part of the document content and red markers represent special control characters which represent the node ranges.

Parameters:
parentElement - The parent element that contains all the new inserted elements.
elementNames - The element names to be inserted.
offsets - The absolute offsets where the elements will be inserted.
namespace - The namespace of the new inserted elements.

insertMultipleFragments

boolean insertMultipleFragments(AuthorElement parentElement,
                                AuthorDocumentFragment[] fragments,
                                int[] offsets)
Insert multiple fragments at the given offsets.
Note: The offsets and fragments must be in document order. The offset must be given in the original document, before any insertion occurs.

To insert two fragment one after another:

          AuthorDocumentFragment[] fragments = new AuthorDocumentFragment[] {frag1, frag2};
          insertMultipleFragments(parentElement, fragments, new int[] {offset, offset});
 
The result of running the above code will be:
   parent
     frag1
     frag2
 


The author content contains the entire XML document text and special marker characters. Each author node points in the content to the start and end marker characters which are used to delimit it's range. The start and end offsets pointed to by the AuthorNode can be retrieved using the AuthorNode.getStartOffset() and AuthorNode.getEndOffset()

The image represents part of the document content and red markers represent special control characters which represent the node ranges.

Parameters:
parentElement - The parent element that contains all the new inserted elements.
fragments - The fragments to be inserted.
offsets - The absolute offsets where the fragments will be inserted. The offset must be given in the original document.
Returns:
true if the operation succeed.
Since:
14

multipleDelete

void multipleDelete(AuthorElement parentElement,
                    int[] startOffsets,
                    int[] endOffsets)
Deletes the given intervals.
Note: The offsets must be in document order and the intervals must not intersect with each other.
The author content contains the entire XML document text and special marker characters. Each author node points in the content to the start and end marker characters which are used to delimit it's range. The start and end offsets pointed to by the AuthorNode can be retrieved using the AuthorNode.getStartOffset() and AuthorNode.getEndOffset()

The image represents part of the document content and red markers represent special control characters which represent the node ranges.

Parameters:
parentElement - The element that contains all the deleted intervals.
startOffsets - The start offset for each interval. Must be in document order.
endOffsets - The end offset for each interval. Must be in document order. 0 based and inclusive.

setDoctype

void setDoctype(AuthorDocumentType docType)
Set a new internal document type to the Author content. This is a good method to add new entities (regular or unparsed) to the internal document type of the document. WARNING: if these modifications affect regular entities already inserted and expanded, they will not be re-parsed and their old content will remain rendered as such.

Parameters:
docType - The document type information.

getDoctype

AuthorDocumentType getDoctype()
Returns information about the internal associated document type.

Returns:
The internal associated document type information. If the document does not have an internal Doctype section the method will return null.

getCommonParentNode

AuthorNode getCommonParentNode(AuthorDocument doc,
                               int startOffset,
                               int endOffset)
                               throws javax.swing.text.BadLocationException
Find the common ancestor node of the two offsets.
The author content contains the entire XML document text and special marker characters. Each author node points in the content to the start and end marker characters which are used to delimit it's range. The start and end offsets pointed to by the AuthorNode can be retrieved using the AuthorNode.getStartOffset() and AuthorNode.getEndOffset()

The image represents part of the document content and red markers represent special control characters which represent the node ranges.

Parameters:
doc - The author document.
startOffset - The start offset.
endOffset - The end offset.
Returns:
The common ancestor. Can be the document but it cannot be null.
Throws:
javax.swing.text.BadLocationException

getNodesToSelect

java.util.List<AuthorNode> getNodesToSelect(int selectionStart,
                                            int selectionEnd)
                                            throws javax.swing.text.BadLocationException
Compute the list with nodes to select when a selection is present in editor. Balanced selection and select all nodes between first and last selected nodes.

Parameters:
selectionStart - The selection start.
selectionEnd - The selection end exclusive.
Returns:
The list with nodes that have to be selected.
Throws:
javax.swing.text.BadLocationException

getCommonAncestor

AuthorNode getCommonAncestor(AuthorNode[] nodes)
Get the common parent for the nodes.

Parameters:
nodes - The array which contains the nodes.
Returns:
The common node. This is either a node from the array which is equal with or contains all other nodes or the closest ancestor which contains all the nodes. null if the nodes are not from the same document or do not belong to a document.

getAuthorDocumentNode

AuthorDocument getAuthorDocumentNode()
Returns the edited author document.

Returns:
The author document. The document cannot be null.

setDocumentFilter

void setDocumentFilter(AuthorDocumentFilter authorDocumentFilter)
Sets the AuthorDocumentFilter to be used for altering the document edits.

Parameters:
authorDocumentFilter - The AuthorDocumentFilter to be used.

getDocumentFilter

AuthorDocumentFilter getDocumentFilter()
Gets the AuthorDocumentFilter which is currently set for altering the document edits.

Returns:
the AuthorDocumentFilter which is currently set for altering the document edits or null if no filter was set.
Since:
15.2

getChars

void getChars(int where,
              int len,
              javax.swing.text.Segment chars)
              throws javax.swing.text.BadLocationException
The content represents the entire text content of the Author page + additional markers/sentinels at offsets which are pointed to by the AuthorNodes. Each AuthorNode points to specific start and end character markers in the content. The start and end offsets pointed to by the AuthorNode can be retrieved using the AuthorNode.getStartOffset() and AuthorNode.getEndOffset()

Retrieves a portion of the content into the specified Segment.

Parameters:
where - The starting position >= 0, where + len <= length()
len - The number of characters to be retrieved >= 0
chars - The Segment object to return the characters int.o
Throws:
javax.swing.text.BadLocationException - If the specified position or length are invalid.

getFilteredContent

AuthorFilteredContent getFilteredContent(int start,
                                         int end,
                                         AuthorNodesFilter nodesFilter)
Retrieves the content between the given start and end offset, excluding the content of the invisible nodes (that have display none style property), the content deleted with track changes, the sentinels of inline elements and the content of filtered nodes.
The filtered nodes are the nodes for which AuthorNodesFilter.shouldFilterNode(AuthorNode) returns true.

The content represents the entire text content of the Author page + additional markers/sentinels at offsets which are pointed to by the AuthorNodes. Each AuthorNode points to specific start and end character markers in the content. The start and end offsets pointed to by the AuthorNode can be retrieved using the AuthorNode.getStartOffset() and AuthorNode.getEndOffset()

Retrieves the content from start to end offsets,

Parameters:
start - The starting position >= 0.
end - The end position >= 0, inclusive
nodesFilter - Provides information about the Author nodes that should be filtered.
Returns:
The char sequence representing the filtered Author content.
Since:
12.1

getAuthorSchemaManager

AuthorSchemaManager getAuthorSchemaManager()
Returns:
The schema manager associated with this document. Null value is returned if there is no schema associated.

insertXMLFragmentSchemaAware

SchemaAwareHandlerResult insertXMLFragmentSchemaAware(java.lang.String xmlFragment,
                                                      java.lang.String xpathLocation,
                                                      java.lang.String relativePosition)
                                                      throws AuthorOperationException
Insert an XML fragment relative to the node identified by the xpathLocation and according with the relativePosition. Note: if the xpathLocation is not specified then the XML fragment will be inserted at caret position and the relativePosition will be ignored.

For more details about schema aware solutions see comments from insertXMLFragmentSchemaAware(String, int) method.

Parameters:
xmlFragment - The XML fragment.
xpathLocation - The XPath location.
relativePosition - The position relative to the node identified by the XPath location. Can be one of the constants: AuthorConstants.POSITION_BEFORE, AuthorConstants.POSITION_AFTER, AuthorConstants.POSITION_INSIDE_FIRST or AuthorConstants.POSITION_INSIDE_LAST.
Returns:
The result of the schema aware insertion.
Throws:
AuthorOperationException - If the fragment could not be inserted.
See Also:
insertXMLFragmentSchemaAware(String, int)

isEditable

boolean isEditable(AuthorNode node)
Test if a node is editable or not. A node is not editable for one of the following cases:
  • the CSS property 'editable' is to 'false';
  • the node is entirely included into a DELETED change marker.
    • Parameters:
      node - The node to test if is editable.
      Returns:
      True if the node is editable, false otherwise.

renameElement

void renameElement(AuthorElement contextNode,
                   java.lang.String newName)
Rename an Author Element, set another qualified name to it.

Parameters:
contextNode - The element to rename.
newName - The new qualified name to set to it.
Since:
12.1

getTextContentIterator

TextContentIterator getTextContentIterator(int startOffset,
                                           int endOffset)
Get an iterator over the text content between two offsets.

Parameters:
startOffset - Start offset, 0 based, inclusive.
endOffset - End offset, 0 based, inclusive.
Returns:
The text content iterator
Since:
13

createPositionInContent

javax.swing.text.Position createPositionInContent(int offset)
                                                  throws javax.swing.text.BadLocationException
Create a flexible position in the Author Content. The position is updated automatically when modifications occur before it. It behaves exactly like a Position added to a swing Document.

Parameters:
offset - The offset where to create the position
Returns:
The created position.
Throws:
javax.swing.text.BadLocationException
Since:
13

addClipboardFragmentProcessor

void addClipboardFragmentProcessor(ClipboardFragmentProcessor clipboardFragmentProcessor)
Add a processor which can analyze and modify AuthorDocumentFragment objects before they are inserted in the Author. The processor specified in the ExtensionsBundle will have maximum priority.

Parameters:
clipboardFragmentProcessor - a processor which can analyze and modify AuthorDocumentFragment objects before they are inserted in the Author.
Since:
13

removeClipboardFragmentProcessor

void removeClipboardFragmentProcessor(ClipboardFragmentProcessor clipboardFragmentProcessor)
Remove a processor which can analyze and modify AuthorDocumentFragment objects before they are inserted in the Author.

Parameters:
clipboardFragmentProcessor - a processor which can analyze and modify AuthorDocumentFragment objects before they are inserted in the Author.
Since:
13

addUniqueAttributesProcessor

void addUniqueAttributesProcessor(UniqueAttributesProcessor uniqueAttributesProcessor)
Add a processor which is asked to automatically generate unique IDs after content has been inserted in the Author. The processor can also specify which attributes can be copied on split. The UniqueAttributesRecognizer specified in the ExtensionsBundle will have maximum priority.

Parameters:
uniqueAttributesProcessor - a processor which is asked to automatically generate unique IDs after content has been inserted in the Author. The processor can also specify which attributes can be copied on split.
Since:
13

getUniqueAttributesProcessor

UniqueAttributesProcessor getUniqueAttributesProcessor()

Get the compound unique attributes processor which can be asked if a certain attribute should get copied on a split.

Returns:
The compound unique attributes processor which can be asked if a certain attribute should get copied on a split.
Since:
15.2

removeUniqueAttributesProcessor

void removeUniqueAttributesProcessor(UniqueAttributesProcessor uniqueAttributesProcessor)
Remove a processor which is asked to automatically generate unique IDs after content has been inserted in the Author. The processor can also specify which attributes can be copied on split. The UniqueAttributesRecognizer specified in the ExtensionsBundle will have maximum priority.

Parameters:
uniqueAttributesProcessor - a processor which is asked to automatically generate unique IDs after content has been inserted in the Author. The processor can also specify which attributes can be copied on split.
Since:
13

findNodesByXPath

AuthorNode[] findNodesByXPath(java.lang.String xpathExpression,
                              AuthorNode contextNode,
                              boolean ignoreTexts,
                              boolean ignoreCData,
                              boolean ignoreComments,
                              boolean processChangeMarkers)
                              throws AuthorOperationException
Finds the author nodes selected by the given XPath 2.0 expression. The result of this function is an array of AuthorNode selected by the given XPath expression. Author text nodes, Author CDATA section nodes and Author comment nodes can be ignored for performance reasons.
For example executing the expression:
//node()
will return an array with all the AuthorNode's in the document.
But the result of calling the function with the expression:
count(//node())
will return an empty array. If change tracking (insert/remove/comment) markers exist in the document they will be ignored and the XPath will return results as if the insert changes are accepted, the delete changes are rejected and the comment changes are ignored.

Parameters:
xpathExpression - The XPath expression. If the XPath expression is relative, it will be computed in the context of the current caret position.
contextNode - The node in the context of which the relative XPath Expressions will computed. If null the context node will be the node at the current caret position.
ignoreTexts - If true Author text nodes will not be returned.
ignoreCData - If true Author CDATA sections will not be returned.
ignoreComments - If true Author comments will not be returned.
processChangeMarkers - If false the change markers (inserts/deletes/comments) will be ignored and the XPath will return results as if the insert changes are accepted, the delete changes are rejected and the comment changes are ignored. If true the XPath will be applied over the document as if the change markers are applied. (All changes processed to processing instructions like when the XML document gets saved on disk).
Returns:
The Author nodes selected by the XPath expression. It does not return a null array of nodes. If the evaluation of the XPath expression fails it will return an empty array.
Throws:
AuthorOperationException - If the XPath expression failed to be evaluated.
Since:
13

findNodesByXPath

AuthorNode[] findNodesByXPath(java.lang.String xpathExpression,
                              AuthorNode contextNode,
                              boolean ignoreTexts,
                              boolean ignoreCData,
                              boolean ignoreComments,
                              boolean processChangeMarkers,
                              XPathVersion xpathVersion)
                              throws AuthorOperationException
Finds the author nodes selected by the given XPath expression. The result of this function is an array of AuthorNode selected by the given XPath expression. Author text nodes, Author CDATA section nodes and Author comment nodes can be ignored for performance reasons.
For example executing the expression:
//node()
will return an array with all the AuthorNode's in the document.
But the result of calling the function with the expression:
count(//node())
will return an empty array. If change tracking (insert/remove/comment) markers exist in the document they will be ignored and the XPath will return results as if the insert changes are accepted, the delete changes are rejected and the comment changes are ignored.

Parameters:
xpathExpression - The XPath expression. If the XPath expression is relative, it will be computed in the context of the current caret position.
contextNode - The node in the context of which the relative XPath Expressions will computed. If null the context node will be the node at the current caret position.
ignoreTexts - If true Author text nodes will not be returned.
ignoreCData - If true Author CDATA sections will not be returned.
ignoreComments - If true Author comments will not be returned.
processChangeMarkers - If false the change markers (inserts/deletes/comments) will be ignored and the XPath will return results as if the insert changes are accepted, the delete changes are rejected and the comment changes are ignored. If true the XPath will be applied over the document as if the change markers are applied. (All changes processed to processing instructions like when the XML document gets saved on disk).
xpathVersion - Used version of XPath.
Returns:
The Author nodes selected by the XPath expression. It does not return a null array of nodes. If the evaluation of the XPath expression fails it will return an empty array.
Throws:
AuthorOperationException - If the XPath expression failed to be evaluated.
Since:
15

evaluateXPath

java.lang.Object[] evaluateXPath(java.lang.String xpathExpression,
                                 AuthorNode contextNode,
                                 boolean ignoreTexts,
                                 boolean ignoreCData,
                                 boolean ignoreComments,
                                 boolean processChangeMarkers)
                                 throws AuthorOperationException
Evaluates an XPath 2.0 expression. This function returns the result of the given XPath expression as an array of Object. Author DOM text nodes, DOM CDATA sections and DOM comment wrappers can be ignored for performance reasons.
For example, executing the expression:
//node()
will return an array with all the Author DOM Node wrappers in the document.
while evaluating the expression:
count(//node())
will return an array having a single component representing the number of nodes in the document.
Evaluating the expression:
//node(), count(//node())
will return an array containing all the Author DOM Node wrappers in the document and having as last component the total number of nodes.

You can also use the XPath extension functions oxy:current-selected-element() and oxy:allows-child-element().

Parameters:
xpathExpression - The XPath expression. If the XPath expression is relative, it will be computed in the context of the context node.
contextNode - The node in the context of which the relative XPath Expressions will computed. If null the context node will be the node at the current caret position.
ignoreTexts - If true DOM text nodes will not be returned.
ignoreCData - If true DOM CDATA sections will not be returned.
ignoreComments - If true DOM comments will not be returned.
processChangeMarkers - If false the change markers (inserts/deletes/comments) will be ignored and the XPath will return results as if the insert changes are accepted, the delete changes are rejected and the comment changes are ignored. If true the XPath will be applied over the document as if the change markers are applied. (All changes processed to processing instructions like when the XML document gets saved on disk).
Returns:
An array of objects representing the XPath result. It does not return a null array. If the XPath evaluation fails it will return an empty array.
Throws:
AuthorOperationException - If the XPath expression failed to be evaluated.
Since:
13

unwrapDocumentFragment

AuthorDocumentFragment unwrapDocumentFragment(AuthorDocumentFragment fragmentToUnwrap)
                                              throws javax.swing.text.BadLocationException
Unwrap a given Author document fragment. If the given fragment has a root element, this method returns a fragment containing the content of the root (or null if the root is empty), else the given fragment is returned.

The author content contains the entire XML document text and special marker characters. Each author node points in the content to the start and end marker characters which are used to delimit it's range. The start and end offsets pointed to by the AuthorNode can be retrieved using the AuthorNode.getStartOffset() and AuthorNode.getEndOffset()
The following image represents the architecture of an Author document fragment that is a part of the document content. The red markers represent special control characters which represent the node ranges:

Parameters:
fragmentToUnwrap - The Author document fragment to be unwrapped.
Returns:
The content of the fragment root (null if the root is empty) or the given fragment.
Throws:
javax.swing.text.BadLocationException - When the offsets are not between 0 and the content length, or the startOffset is greater than the endOffset.
Since:
14

getUnparsedEntityUri

java.lang.String getUnparsedEntityUri(AuthorNode contextNode,
                                      java.lang.String entityName)
Returns the URI of the unparsed entity with the specified name, in the same document as the context node.

Parameters:
contextNode - Context node.
entityName - Unparsed entity name.
Returns:
The URI of the entity or null if the entity is undefined.
Since:
14.2

refreshNodeReferences

void refreshNodeReferences(AuthorNode node)

Refresh node references recursively. If a node has expanded references on it created using the "ro.sync.ecss.extensions.api.AuthorReferenceResolver" API this method will call again the API to provide a fresh reference content for the node.

Parameters:
node - The node on which to refresh the references.
Since:
15.2

setRenderingInfoChangedListener

void setRenderingInfoChangedListener(RenderingInfoChangedListener listener)

Sets the listener to be notified when the rendering info of a node has changed.

The rendering info is represented by the node's styles computed from the associated CSS stylesheet and its content.

Parameters:
listener - The listener.
Since:
15.2

getXPathExpression

java.lang.String getXPathExpression(int offset)
                                    throws javax.swing.text.BadLocationException
Returns the XPath expression of the node identified by the given offset. The offset must be a valid document offset.
Nodes deleted with change tracking are also considered when creating the context for the XPath expression.

Parameters:
offset - The offset of the node to get the XPath expression for.
Returns:
The XPath expression of the element from the given offset or an empty string if no XPath could be found.
Throws:
javax.swing.text.BadLocationException - When the offset is outside the valid interval (0 and the content length).
Since:
16.1

*********************************
EXPERIMENTAL - Subject to change
********************************

Please note that this API is not marked as final and it can change in one of the next versions of the application. If you have suggestions, comments about it, please let us know.


Oxygen XML Editor 16.1 Author API

© Copyright SyncRO Soft SRL 2002 - 2014. All rights reserved.