|
Oxygen XML Editor 11.2 Author API | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
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 |
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 a document fragment for the given range of offsets. |
AuthorDocumentFragment |
createNewDocumentFragmentInContext(String xmlFragment,
int contentOffset)
Create a new AuthorDocumentFragment from an XML string in a specified context. |
AuthorDocumentFragment |
createNewDocumentTextFragment(String textFragment)
Create a new AuthorDocumentFragment from an string. |
boolean |
delete(int startOffset,
int endOffset)
Deletes a document fragment between the start and end offset. |
boolean |
deleteNode(AuthorNode node)
Delete a node. |
void |
endCompoundEdit()
End a compound edit. |
Object[] |
evaluateXPath(String xpathExpression,
boolean ignoreTexts,
boolean ignoreCData,
boolean ignoreComments)
Evaluates an XPath expression. |
AuthorNode[] |
findNodesByXPath(String xpathExpression,
boolean ignoreTexts,
boolean ignoreCData,
boolean ignoreComments)
Finds the author nodes selected by the given XPath expression. |
AuthorDocument |
getAuthorDocumentNode()
Returns the edited author document. |
AuthorSchemaManager |
getAuthorSchemaManager()
|
void |
getChars(int where,
int len,
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 |
getCommonParentNode(AuthorDocument doc,
int startOffset,
int endOffset)
Find the common ancestor node of the two offsets. |
AuthorDocumentType |
getDoctype()
Returns information about the internal associated document type. |
AuthorNode |
getNodeAtOffset(int offset)
Returns the node at the given offset. |
String |
getText(int offset,
int length)
Deprecated. Use the API based on the AuthorNode to get only the displayed text
without mark-up markers. |
int |
getTextContentLength()
Deprecated. Use the API based on the AuthorNode to get the length
of the displayed text only, without mark-up markers. |
UndoManager |
getUndoManager()
Get access to the Author undo manager. |
int |
getXPathLocationOffset(String xpathLocation,
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 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,
String[] elementNames,
int[] offsets,
String namespace)
Insert multiple elements at the given offsets. |
void |
insertText(int offset,
String text)
Inserts a text at the given offset. |
void |
insertXMLFragment(String xmlFragment,
AuthorNode relativeTo,
String relativePosition)
Insert an XML fragment relative to the given node and according with the relativePosition . |
void |
insertXMLFragment(String xmlFragment,
int offset)
Insert an XML fragment at the given offset. |
void |
insertXMLFragment(String xmlFragment,
String xpathLocation,
String relativePosition)
Insert an XML fragment relative to the node identified by the xpathLocation
and according with the relativePosition . |
SchemaAwareHandlerResult |
insertXMLFragmentSchemaAware(String xmlFragment,
int offset)
Insert an XML fragment at the given offset in schema aware mode. |
SchemaAwareHandlerResult |
insertXMLFragmentSchemaAware(String xmlFragment,
String xpathLocation,
String relativePosition)
Insert an XML fragment relative to the node identified by the xpathLocation
and according with the relativePosition . |
void |
multipleDelete(AuthorElement parentElement,
int[] startOffsets,
int[] endOffsets)
Deletes the given intervals. |
void |
removeAttribute(String attributeName,
AuthorElement element)
Removes an attribute from the given element. |
void |
removeAuthorListener(AuthorListener listener)
Remove an Author listener. |
void |
replaceRoot(AuthorDocumentFragment fragment)
Replace the current root element with the new given one. |
String |
serializeFragmentToXML(AuthorDocumentFragment fragment)
Takes the given fragment and serializes it to XML text in the context of the current document. |
void |
setAttribute(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 |
surroundInFragment(String xmlFragment,
int startOffset,
int endOffset)
Surround the content between the given offsets with the xmlFragment . |
void |
surroundInText(String header,
String footer,
int startOffset,
int endOffset)
Surround the content between the given offsets with plain text fragments(without XML parsing). |
Method Detail |
---|
boolean delete(int startOffset, int endOffset)
startOffset
- Start offset, 0 based, inclusive.endOffset
- End offset, 0 based, inclusive.
true
if the delete operation was successful.boolean deleteNode(AuthorNode node)
node
- The AuthorNode
to delete.
true
if the delete node operation was successful.void replaceRoot(AuthorDocumentFragment fragment)
fragment
- The document fragment containing the new root element.AuthorDocumentFragment createDocumentFragment(int startOffset, int endOffset) throws BadLocationException
startOffset
- The start offset, 0 based, inclusive.endOffset
- The end offset, 0 based, inclusive.
AuthorDocumentFragment
.
It does not return a null
fragment.
BadLocationException
- When the offsets are not between 0 and the
content length, or the startOffset
is greater than the endOffset
.AuthorDocumentFragment createNewDocumentFragmentInContext(String xmlFragment, int contentOffset) throws AuthorOperationException
AuthorDocumentFragment
from an XML string in a specified context.
xmlFragment
- The XML Fragment.contentOffset
- The offset where the XML fragment should be inserted.
AuthorDocumentFragment
.
It does not return a null
fragment.
AuthorOperationException
- If the new fragment creation fails.AuthorDocumentFragment createNewDocumentTextFragment(String textFragment) throws AuthorOperationException
AuthorDocumentFragment
from an string.
textFragment
- The text fragment.
AuthorDocumentFragment
.
It does not return a null
fragment.
AuthorOperationException
- If the new fragment creation fails.String serializeFragmentToXML(AuthorDocumentFragment fragment) throws BadLocationException
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()); }
fragment
- The AuthorDocumentFragment
to serialize.
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.
BadLocationException
- If the serialization could not be accomplished,
usually because the fragment was not properly built.void setAttribute(String attributeName, AttrValue value, AuthorElement element)
AuthorElement.setAttribute(String, AttrValue)
directly)
will be subject to undo/redo.
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.void removeAttribute(String attributeName, AuthorElement element)
AuthorElement.setAttribute(String, AttrValue)
directly) will
be subject to undo/redo.
attributeName
- Name of the attribute to remove.element
- The AuthorElement
whose attribute will be removed.AuthorNode getNodeAtOffset(int offset) throws BadLocationException
offset
- The offset in the content, zero based.
AuthorNode
containing the offset,
or null
when the actual document is null
.
BadLocationException
- When the offset is negative or greater
than the content length.AuthorDocumentFragment createDocumentFragment(AuthorNode node, boolean copyContent) throws BadLocationException
copyContent
is true
the node content
will be copied also.
node
- The AuthorNode
to be duplicated.copyContent
- If true
the content of the node will
also be duplicated.
AuthorDocumentFragment
containing the duplicated node.
It does not return a null
fragment.
BadLocationException
- When the operation fails.@Deprecated String getText(int offset, int length) throws BadLocationException
AuthorNode
to get only the displayed text
without mark-up markers.
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.
length
represents also a number of valid chars encountered
after the real start offset was determined.
[?PI?][article][!COMMENT][para]PARAGRAPH[/para][/article]
getText(0, 18)
returns "PICOMMENTPARAGRAPH"
getText(5, 8)
returns "MENTPARA"
offset
- The starting offset >= 0.length
- The number of characters to retrieve >= 0
BadLocationException
- The range given includes a position
that is not a valid position within the document text content.@Deprecated int getTextContentLength() throws BadLocationException
AuthorNode
to get the length
of the displayed text only, without mark-up markers.
[?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:
BadLocationException
UndoManager getUndoManager()
null
.void beginCompoundEdit()
beginCompoundEdit()
and endCompoundEdit()
methods calls are regarded by the UndoManager
as a single operation which can be undone/redone in one step.
void endCompoundEdit()
beginCompoundEdit()
void cancelCompoundEdit()
beginCompoundEdit()
will be undo by the UndoManager.
beginCompoundEdit()
,
endCompoundEdit()
void insertText(int offset, String text)
offset
- The insert position, 0 based.text
- The text to be inserted.void insertXMLFragment(String xmlFragment, int offset) throws AuthorOperationException
xmlFragment
- The XML fragment to insert.offset
- The insert position, 0 based.
AuthorOperationException
- If the fragment could not be inserted.void insertXMLFragment(String xmlFragment, String xpathLocation, String relativePosition) throws AuthorOperationException
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 at the end of the inserted XML 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.
void insertXMLFragment(String xmlFragment, AuthorNode relativeTo, String relativePosition) throws AuthorOperationException
relativePosition
.
After the operation the caret will be positioned at the end of the inserted XML fragment.
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
.
AuthorOperationException
- If the fragment could not be inserted.SchemaAwareHandlerResult insertXMLFragmentSchemaAware(String xmlFragment, int offset) throws AuthorOperationException
<sect1> <title>Section title</title> {caret} <para>para content</para> </sect1>if insert a fragment like:
<emphasis>text</emphasis>
the proposal is to
create a new para
element and insert the fragment inside it. The proposal result will be:
<sect1> <title>Section title</title> <para><emphasis>text</emphasis></para> <para>para content</para> </sect1>
<sect1> <title>Section title</title> {caret} <para>para content</para> </sect1>if insert a fragment like:
<sect1>...section content...</sect1>
the proposal is to
split the parent sect1
element and insert the fragment between the resulted sections. The proposal result will be:
<sect1> <title>Section title</title> </sect1> <sect1>...section content...</sect1> <sect1> <para>para content</para> </sect1>
<sect1> <title>Section title</title> {caret} <para>para content</para> </sect1>if insert a fragment like:
<emphasis>text</emphasis>
the proposals are to
insert the fragment at the end of title
or at beginning of para
element.
<sect1> <title>Section title {caret}</title> </sect1>if insert a fragment like:
<para>fragment <emphasis>content</emphasis></para>
the proposal is to remove the fragment mark-up and insert the text 'fragment content' at caret position.
The proposal result will be:
<sect1> <title>Section title fragment content</title> </sect1>
If the developer specifies an AuthorSchemaAwareEditingHandler
then this handler has priority
for executing the insert operation.
xmlFragment
- The XML fragment to insert.offset
- The insert position, 0 based.
AuthorOperationException
- If the fragment could not be inserted.void insertFragment(int insertOffset, AuthorDocumentFragment frag)
AuthorDocumentFragment
at the given offset.
insertOffset
- The offset where the fragment will be inserted, 0 based.frag
- The AuthorDocumentFragment
to be inserted.SchemaAwareHandlerResult insertFragmentSchemaAware(int insertOffset, AuthorDocumentFragment frag) throws AuthorOperationException
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.
insertOffset
- The offset where the fragment will be inserted, 0 based.frag
- The AuthorDocumentFragment
to be inserted.
AuthorOperationException
- If the fragment could not be inserted.void surroundInFragment(String xmlFragment, int startOffset, int endOffset) throws AuthorOperationException
xmlFragment
.
If endOffset < startOffset
the xmlFragment
will be inserted at startOffset
.
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.
AuthorOperationException
- If the content between start and end offset could not be surrounded.void surroundInText(String header, String footer, int startOffset, int endOffset) throws AuthorOperationException
header
at startOffset
and
the footer
at endOffset
.
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.
AuthorOperationException
- If the operation failed.boolean inInlineContext(int offset) throws BadLocationException, AuthorOperationException
offset
is inline or not.
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
.
offset
- The offset in the document, zero based.
true
if the given offset is inside an inline context.
false
otherwise.
BadLocationException
- When the offset does not exists in the document content.
AuthorOperationException
- If the operation failed.void addAuthorListener(AuthorListener listener)
listener
- The AuthorListener
to be added.void removeAuthorListener(AuthorListener listener)
listener
- The AuthorListener
to be removed.Object[] evaluateXPath(String xpathExpression, boolean ignoreTexts, boolean ignoreCData, boolean ignoreComments) throws AuthorOperationException
Object
.
Author DOM text nodes, DOM CDATA sections and DOM comment wrappers can be
ignored for performance reasons.
//node()
will return an array with all the Author DOM Node wrappers in the document.
count(//node())
will return an array having a single component representing the number of nodes in the document.
//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.
xpathExpression
- The XPath expression.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.
null
array. If the XPath evaluation fails it will return
an empty array.
AuthorOperationException
- If the XPath expression failed to be evaluated.AuthorNode[] findNodesByXPath(String xpathExpression, boolean ignoreTexts, boolean ignoreCData, boolean ignoreComments) throws AuthorOperationException
AuthorNode
selected
by the given XPath expression.
Author text nodes, Author CDATA section nodes and Author comment nodes
can be ignored for performance reasons.
//node()
will return an array with all the AuthorNode's in the document.
count(//node())
will return an empty array.
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.
null
array of nodes.
If the evaluation of the XPath expression fails it will return an empty array.
AuthorOperationException
- If the XPath expression failed to be evaluated.int getXPathLocationOffset(String xpathLocation, String relativePosition) throws AuthorOperationException
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
AuthorOperationException
- If it fails.void insertMultipleElements(AuthorElement parentElement, String[] elementNames, int[] offsets, String namespace)
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.void multipleDelete(AuthorElement parentElement, int[] startOffsets, int[] endOffsets)
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.void setDoctype(AuthorDocumentType docType)
docType
- The document type information.AuthorDocumentType getDoctype()
null
.AuthorNode getCommonParentNode(AuthorDocument doc, int startOffset, int endOffset) throws BadLocationException
doc
- The author document.startOffset
- The start offset.endOffset
- The end offset.
null
.
BadLocationException
AuthorDocument getAuthorDocumentNode()
null
.void setDocumentFilter(AuthorDocumentFilter authorDocumentFilter)
AuthorDocumentFilter
to be used for altering the document edits.
authorDocumentFilter
- The AuthorDocumentFilter
to be used.void getChars(int where, int len, Segment chars) throws BadLocationException
Segment
.
where
- The starting position >= 0, where + len <= length()len
- The number of characters to be retrieved >= 0chars
- The Segment
object to return the characters int.o
BadLocationException
- If the specified position or length are invalid.AuthorSchemaManager getAuthorSchemaManager()
SchemaAwareHandlerResult insertXMLFragmentSchemaAware(String xmlFragment, String xpathLocation, String relativePosition) throws AuthorOperationException
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)
|
Oxygen XML Editor 11.2 Author API | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |