Oxygen XML Editor 16.1 Author API

ro.sync.exml.workspace.api.editor.page.author
Interface WSAuthorEditorPageBase

All Superinterfaces:
WSEditorPage, WSTextBasedEditorPage
All Known Subinterfaces:
AuthorEditorAccess, WSAuthorComponentEditorPage, WSAuthorEditorPage

@API(type=NOT_EXTENDABLE,
     src=PUBLIC)
public interface WSAuthorEditorPageBase
extends WSTextBasedEditorPage

Provides access to methods related to the Author editor actions and information.

Since:
11.2

Method Summary
 void addAuthorAttributesDisplayFilter(AuthorAttributesDisplayFilter attributesDisplayFilter)
          Adds a filter for displaying attributes to the current author page.
 void addAuthorCaretListener(AuthorCaretListener caretListener)
          Adds a caret listener to the Author page.
 void addAuthorMouseListener(AuthorMouseListener mouseListener)
          Adds a mouse listener to the current author page.
 void addPopUpMenuCustomizer(AuthorPopupMenuCustomizer popUpCustomizer)
          Add the pop-up menu customizer which can be used to customize the pop-up menu (add/remove actions) before showing it in the Author page.
 void deleteSelection()
          Delete the current selected text, if any.
 void editAttribute(AuthorElement targetElement, java.lang.String attributeName)
          Searches through the in-place editors added on the given element for the first one that edits the given attribute.
 AuthorActionsProvider getActionsProvider()
          Provides access to actions already defined in the Author page like: Undo, Redo, Display Full Tags, Edit Attributes, etc.
 java.lang.Object getAuthorComponent()
          Get the internal component on which the Author page is rendered.
 AuthorSelectionModel getAuthorSelectionModel()
          Get the Author selection model containing access to all Author selection intervals and methods for adding simple and multiple selections.
 int[] getBalancedSelection(int selectionStart, int selectionEnd)
          Usually returns the selection.
 int getBalancedSelectionEnd()
          Usually returns the same value as getSelectionEnd().
 int getBalancedSelectionStart()
          Usually returns the same value as getSelectionStart().
 AuthorSchemaAwareEditingHandler getDefaultAuthorSchemaAwareEditingHandler()
          Get the default schema aware editing handler.
 AuthorNode getFullySelectedNode()
          Get the node which is fully and perfectly surrounded by the current selection in the Author editor.
If the selection surrounds perfectly the node (the selection starts at the node start offset and ends immediately after the node end offset), the node will be returned, otherwise null will be returned.
For example if a node is selected using Outline or the Breadcrumb, the method will return the corresponding node.
 AuthorNode getFullySelectedNode(int selectionStart, int selectionEnd)
          Get the node which is fully and perfectly surrounded by the given selection in the Author editor.
If the selection surrounds perfectly the node (the selection starts at the node start offset and ends immediately after the node end offset), the node will be returned, otherwise null will be returned.
For example if a node is selected using Outline or the Breadcrumb, the method will return the corresponding node.
 AuthorHighlighter getHighlighter()
          Get the highlighter which can be used to add/remove/manage the custom user highlights
 AuthorPersistentHighlighter getPersistentHighlighter()
          Get the persistent highlighter which can be used to add/remove/manage the custom persistent user highlights.
 java.lang.String getSelectedText()
          Get the current selected text.
 int getSelectionEnd()
          Get end offset of the current selection.
 int getSelectionStart()
          Get start offset of the current selection.
 Styles getStyles(AuthorNode node)
          Get the CSS styles which are used to render a particular Author node.
 void goToNextEditablePosition(int startOffset, int endOffset)
          Identifies and goes to the next edit position.
 boolean hasSelection()
          Check if the editor page has a selection

Use AuthorSelectionModel to get more information and access to the Author editor page selection.
 boolean isOffsetInInvisibleBounds(int offset)
          Check whether the offset is in a region in the document which is not rendered.
 void refresh()
          Reload the CSS files and perform a refresh on the whole document to recompute the layout and the styles for all the nodes based on the new CSS files content.
 void refresh(AuthorNode authorNode)
          Refresh the rendering layout and CSS styles for this node and all its contents.
 void removeAuthorAttributesDisplayFilter(AuthorAttributesDisplayFilter attributesDisplayFilter)
          Remove a filter for displaying attributes to the current author page.
 void removeAuthorCaretListener(AuthorCaretListener caretListener)
          Removes the specified caret listener from the Author page.
 void removeAuthorMouseListener(AuthorMouseListener mouseListener)
          Removes the specified mouse listener from the current author page.
 void removePopUpMenuCustomizer(AuthorPopupMenuCustomizer popUpCustomizer)
          Add the pop-up menu customizer which can be used to customize the pop-up menu (add/remove actions) before showing it in the Author page.
 void scrollToRectangle(Rectangle rectangle)
          Scroll the Author viewport to a specific rectangle.
 void select(int startOffset, int endOffset)
          Select the interval between start and end offset.
 void setPopUpMenuCustomizer(AuthorPopupMenuCustomizer popUpCustomizer)
          Deprecated. This method removes all pop-up menu customizers already registered, please use the "addPopUpMenuCustomizer" method instead.
 AuthorViewToModelInfo viewToModel(int x, int y)
          Get the position in the document corresponding to the point in the author viewport component.
 
Methods inherited from interface ro.sync.exml.workspace.api.editor.page.WSTextBasedEditorPage
getCaretOffset, getLocationOnScreenAsPoint, getLocationRelativeToEditorFromScreen, getStartEndOffsets, getWordAtCaret, isEditable, modelToViewRectangle, selectWord, setCaretPosition, setEditable, viewToModelOffset
 

Method Detail

viewToModel

AuthorViewToModelInfo viewToModel(int x,
                                  int y)
Get the position in the document corresponding to the point in the author viewport component.

Parameters:
x - The "x" coordinate relative to the viewport origin.
y - The "y" coordinate relative to the viewport origin.
Returns:
The AuthorViewToModelInfo containing the offset and the node at offset corresponding to the given point. The method does not return null, instead an undefined view to model info object is returned if a valid one could not be determined.

setPopUpMenuCustomizer

@Deprecated
void setPopUpMenuCustomizer(AuthorPopupMenuCustomizer popUpCustomizer)
Deprecated. This method removes all pop-up menu customizers already registered, please use the "addPopUpMenuCustomizer" method instead.

Set the pop-up menu customizer which can be used to customize the pop-up menu (add/remove actions) before showing it in the Author page.

Parameters:
popUpCustomizer - the pop-up menu customizer.

addPopUpMenuCustomizer

void addPopUpMenuCustomizer(AuthorPopupMenuCustomizer popUpCustomizer)
Add the pop-up menu customizer which can be used to customize the pop-up menu (add/remove actions) before showing it in the Author page.

Parameters:
popUpCustomizer - the pop-up menu customizer. If the customizer is already added, it will not be added again.
Since:
14.1

removePopUpMenuCustomizer

void removePopUpMenuCustomizer(AuthorPopupMenuCustomizer popUpCustomizer)
Add the pop-up menu customizer which can be used to customize the pop-up menu (add/remove actions) before showing it in the Author page.

Parameters:
popUpCustomizer - the pop-up menu customizer.
Since:
14.1

addAuthorMouseListener

void addAuthorMouseListener(AuthorMouseListener mouseListener)
Adds a mouse listener to the current author page.

Parameters:
mouseListener - The AuthorMouseListener to be added.

removeAuthorMouseListener

void removeAuthorMouseListener(AuthorMouseListener mouseListener)
Removes the specified mouse listener from the current author page.

Parameters:
mouseListener - The AuthorMouseListener to be removed.

addAuthorCaretListener

void addAuthorCaretListener(AuthorCaretListener caretListener)
Adds a caret listener to the Author page.

Parameters:
caretListener - The AuthorCaretListener to be added.

removeAuthorCaretListener

void removeAuthorCaretListener(AuthorCaretListener caretListener)
Removes the specified caret listener from the Author page.

Parameters:
caretListener - The AuthorCaretListener to be removed.

refresh

void refresh(AuthorNode authorNode)
Refresh the rendering layout and CSS styles for this node and all its contents.

Note: This should be called on the AWT thread because it will generate a layout event.

Parameters:
authorNode - The node for which the layout and styles will be recomputed.

refresh

void refresh()
Reload the CSS files and perform a refresh on the whole document to recompute the layout and the styles for all the nodes based on the new CSS files content.


getHighlighter

AuthorHighlighter getHighlighter()
Get the highlighter which can be used to add/remove/manage the custom user highlights

Returns:
The highlighter which can be used to add/remove/manage the custom user highlights.

getPersistentHighlighter

AuthorPersistentHighlighter getPersistentHighlighter()
Get the persistent highlighter which can be used to add/remove/manage the custom persistent user highlights.
Persistent highlights get serialized in the XML as processing instructions with the form:
<?oxy_custom_start prop1="val1"....?> xml content <?oxy_custom_end?>

Returns:
The persistent highlighter which can be used to add/remove/manage the custom user highlights.
Since:
12

getBalancedSelectionStart

int getBalancedSelectionStart()
Usually returns the same value as getSelectionStart().
If the selection start is immediately to the right of a start tag and the corresponding end tag is contained in the selection, then the balanced selection start will be obtained by extending the selection start to contain the start tag.

Returns:
The balanced selection start offset, 0 based.
Since:
12

getBalancedSelectionEnd

int getBalancedSelectionEnd()
Usually returns the same value as getSelectionEnd().
If the selection end is immediately to the left of a end tag and the corresponding start tag is contained in the selection, then the balanced selection end will be obtained by extending the selection end to contain the end tag.

Returns:
The balanced selection end offset, 0 based.
Since:
12

getBalancedSelection

int[] getBalancedSelection(int selectionStart,
                           int selectionEnd)
Usually returns the selection.
If the selection start is immediately to the right of a start tag and the corresponding end tag is contained in the selection, then the balanced selection start will be obtained by extending the selection start to contain the start tag. If the selection end is immediately to the left of a end tag and the corresponding start tag is contained in the selection, then the balanced selection end will be obtained by extending the selection end to contain the end tag.

Parameters:
selectionStart - The inclusive selection start.
selectionEnd - The exclusive selection end.
Returns:
The balanced selection obtained from the given selection, 0 based. The first element of the returned array represents the selection start. and the second element represents the selection end.
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.


getDefaultAuthorSchemaAwareEditingHandler

AuthorSchemaAwareEditingHandler getDefaultAuthorSchemaAwareEditingHandler()
Get the default schema aware editing handler. This can be used from a custom AuthorSchemaAwareEditingHandler implementation from an ExtensionsBundle to delegate various operations to.

Returns:
the default schema aware editing handler.
Since:
12.1

getActionsProvider

AuthorActionsProvider getActionsProvider()
Provides access to actions already defined in the Author page like: Undo, Redo, Display Full Tags, Edit Attributes, etc.

Returns:
access to actions already defined in the Author page.
Since:
12.1

getAuthorComponent

java.lang.Object getAuthorComponent()
Get the internal component on which the Author page is rendered. Use of this method is discouraged but it may be useful in some cases like: This can be helpful when you want to set a busy cursor on the component for example or when you want to get access to the scroll bars. You can also request focus in the component by casting it to its native equivalent.

Returns:
for the stand alone version, a javax.swing.JPanel and for the eclipse implementation a org.eclipse.swt.widgets.Canvas.
Since:
12.2

getStyles

Styles getStyles(AuthorNode node)
Get the CSS styles which are used to render a particular Author node. This method MUST only be used to query styles. If you want to modify styles please use the StylesFilter.

Parameters:
node - The node for which we want to obtain the styles.
Returns:
the styles associated with the node.
Since:
12.2

addAuthorAttributesDisplayFilter

void addAuthorAttributesDisplayFilter(AuthorAttributesDisplayFilter attributesDisplayFilter)
Adds a filter for displaying attributes to the current author page.

Parameters:
attributesDisplayFilter - The AuthorAttributesDisplayFilter to be added.
Since:
13

removeAuthorAttributesDisplayFilter

void removeAuthorAttributesDisplayFilter(AuthorAttributesDisplayFilter attributesDisplayFilter)
Remove a filter for displaying attributes to the current author page.

Parameters:
attributesDisplayFilter - The AuthorAttributesDisplayFilter to be added.
Since:
13

getFullySelectedNode

AuthorNode getFullySelectedNode()
Get the node which is fully and perfectly surrounded by the current selection in the Author editor.
If the selection surrounds perfectly the node (the selection starts at the node start offset and ends immediately after the node end offset), the node will be returned, otherwise null will be returned.
For example if a node is selected using Outline or the Breadcrumb, the method will return the corresponding node.
In such cases the method AuthorDocumentController.getNodeAtOffset(int) called for the caret offset always returns the parent of the selected element as the caret is actually outside the selected element. Thus, in order to obtain the context node, this method should be used and if it returns null you can use the AuthorDocumentController.getNodeAtOffset(int) method.

Returns:
The selected node if the selection surrounds perfectly the node, null otherwise.
Since:
13.1

getFullySelectedNode

AuthorNode getFullySelectedNode(int selectionStart,
                                int selectionEnd)
Get the node which is fully and perfectly surrounded by the given selection in the Author editor.
If the selection surrounds perfectly the node (the selection starts at the node start offset and ends immediately after the node end offset), the node will be returned, otherwise null will be returned.
For example if a node is selected using Outline or the Breadcrumb, the method will return the corresponding node.
In such cases the method AuthorDocumentController.getNodeAtOffset(int) called for the caret offset always returns the parent of the selected element as the caret is actually outside the selected element. Thus, in order to obtain the context node, this method should be used and if it returns null you can use the AuthorDocumentController.getNodeAtOffset(int) method.

Parameters:
selectionStart - Inclusive start offset.
selectionEnd - Exclusive end offset.
Returns:
The selected node if the given selection surrounds perfectly the node, null otherwise.
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.


getAuthorSelectionModel

AuthorSelectionModel getAuthorSelectionModel()
Get the Author selection model containing access to all Author selection intervals and methods for adding simple and multiple selections.

Returns:
The Author selection model.
Since:
14

getSelectionStart

int getSelectionStart()
Get start offset of the current selection. It is inclusive.

If the Author editor page has multiple selection intervals, this method returns the start offset of the last selected content interval.
Use AuthorSelectionModel to get more information and access to the Author editor page selection.

If there is no selection in Author editor page, the caret offset is returned.

Specified by:
getSelectionStart in interface WSTextBasedEditorPage
Returns:
The selection start offset, 0 based.

getSelectionEnd

int getSelectionEnd()
Get end offset of the current selection. It is exclusive

If the Author editor page has multiple selection intervals, this method returns the end offset of the last selected content interval.
Use AuthorSelectionModel to get more information and access to the Author editor page selection.

If there is no selection in Author editor page, the caret offset is returned.

Specified by:
getSelectionEnd in interface WSTextBasedEditorPage
Returns:
The selection end offset, 0 based.

getSelectedText

java.lang.String getSelectedText()
Get the current selected text. The text does not contain XML tags for the Author page.

If the Author editor page has multiple selection intervals, this method returns the text from the last selected content interval.
Use AuthorSelectionModel to get more information and access to the Author editor page selection.

Specified by:
getSelectedText in interface WSTextBasedEditorPage
Returns:
The selected text or an empty string if no selection is present.

deleteSelection

void deleteSelection()
Delete the current selected text, if any.

If the Author editor page has multiple selection intervals, this method deletes the content from the last selected interval.
Use AuthorSelectionModel to get more information and access to the Author editor page selection.

Specified by:
deleteSelection in interface WSTextBasedEditorPage

hasSelection

boolean hasSelection()
Check if the editor page has a selection

Use AuthorSelectionModel to get more information and access to the Author editor page selection.

Specified by:
hasSelection in interface WSTextBasedEditorPage
Returns:
true if there is a selection, false otherwise.

select

void select(int startOffset,
            int endOffset)
Select the interval between start and end offset.

Use AuthorSelectionModel to get more information and access to the Author editor page selection.

Specified by:
select in interface WSTextBasedEditorPage
Parameters:
startOffset - Inclusive start offset
endOffset - Exclusive end offset

isOffsetInInvisibleBounds

boolean isOffsetInInvisibleBounds(int offset)
                                  throws javax.swing.text.BadLocationException
Check whether the offset is in a region in the document which is not rendered. For example: oxy-collapse-text nodes, 'display: none' nodes or tracked deleted content which is not presented in 'Final' mode.

Parameters:
offset - The offset to check.
Returns:
true if the offset is in an invisible region.
Throws:
javax.swing.text.BadLocationException - If the offset is outside the document.

goToNextEditablePosition

void goToNextEditablePosition(int startOffset,
                              int endOffset)
                              throws javax.swing.text.BadLocationException
Identifies and goes to the next edit position. Depending on which is first, this can be: The offset should be in the given interval specified by startOffset and endOffset exclusive.

Parameters:
startOffset - The offset from where to start looking.
endOffset - The offset where to stop looking for.
Throws:
javax.swing.text.BadLocationException - The given offset is invalid.
Since:
14.1

editAttribute

void editAttribute(AuthorElement targetElement,
                   java.lang.String attributeName)
Searches through the in-place editors added on the given element for the first one that edits the given attribute. If such an editor is found it will activate the editor to start editing. Hypothetically there could be more than one editor for the same attribute (even though is not a real use case nor is it encouraged) but we'll activate the first one we encounter. The search will first look at the BEFORE styles, then the element styles and finally the AFTER styles.

Parameters:
targetElement - The parent element of the attribute.
attributeName - The QName of the searched attribute.
Since:
14.1

scrollToRectangle

void scrollToRectangle(Rectangle rectangle)
Scroll the Author viewport to a specific rectangle. To find the rectangle that corresponds to a specific offset in the Author document you can use the WSTextBasedEditorPage.modelToViewRectangle(int) method.

Parameters:
rectangle - The rectangle to scroll to.
Since:
14.1

Oxygen XML Editor 16.1 Author API

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