Package ro.sync.ecss.extensions.api.highlights

Interface AuthorPersistentHighlighter

  • @API(type=NOT_EXTENDABLE,
     src=PUBLIC)
public interface AuthorPersistentHighlighter
    Manage the user custom persistent highlights which get serialized in the XML as processing instructions with the form:
    <?oxy_custom_start prop1="val1"....?> xml content <?oxy_custom_end?>
    The Highlighter is accessible from WSAuthorEditorPageBase.getPersistentHighlighter().
    Since:
    12

    • Method Detail

      • addHighlight

        AuthorPersistentHighlight addHighlight​(int startOffset,
                                       int endOffset,
                                       java.util.LinkedHashMap<java.lang.String,​java.lang.String> properties)
                                throws java.lang.IllegalArgumentException
        Add a custom persistent highlight.
        The name of the processing instruction markers corresponding to this type of highlight are oxy_custom_start and oxy_custom_end.
        The type of the added persistent highlight is AuthorPersistentHighlight.PersistentHighlightType.CUSTOM_HIGHLIGHT.
        Parameters:
        startOffset - Start offset (inclusive).
        endOffset - End offset (inclusive). The highlight end offset must be equal or greater than the start offset.
        properties - name/value pairs which will get serialized to disk.

        Notes:
        1. Each property name must be a valid XML attribute name.
        2. Each property value will be escaped to be a valid XML attribute value.
        3. In order to change the properties for a highlight you have to use the method: setProperties(AuthorPersistentHighlight, LinkedHashMap).

        Returns:
        The added highlight or null if the highlight cannot be added if for example the offsets are in read-only content or there is a marker with the same properties over the same interval.
        Throws:
        java.lang.IllegalArgumentException - Thrown when a property name is not a valid XML attribute name or when the given end offset is less than start offset.

      • canAddHighlight

        boolean canAddHighlight​(int startOffset,
                        int endOffset)
        Check if a custom AuthorPersistentHighlight can be added for the given start and end offsets. If one of these offsets correspond to a read-only context (they are inside a content deleted with track changes, an element set as read-only from CSS or a content generated from expanding a reference) the highlight cannot be inserted and this method returns false.

        A custom persistent highlight can be added by using the addHighlight(int, int, LinkedHashMap) method. The name of the processing instruction markers corresponding to the custom persistent highlight are oxy_custom_start and oxy_custom_end.
        Parameters:
        startOffset - Start offset (inclusive).
        endOffset - End offset (inclusive). The highlight end offset must be equal or greater than the start offset.
        Returns:
        true if a custom persistent highlight can be inserted
        Since:
        14.1

      • removeHighlight

        void removeHighlight​(AuthorPersistentHighlight highlight)
        Removes a highlight from the view.
        Parameters:
        highlight - the highlight to remove

      • removeAllHighlights

        void removeAllHighlights()
        Removes all custom persistent highlights.

      • getHighlights

        AuthorPersistentHighlight[] getHighlights()
        Fetches the list of custom persistent highlights.
        Returns:
        the highlight array.

      • getHighlights

        AuthorPersistentHighlight[] getHighlights​(int startOffset,
                                          int endOffset)
        Fetches the list of custom persistent highlights that intersect the interval between the given start offset and end offset.
        Parameters:
        startOffset - The start offset(inclusive).
        endOffset - The end offset (inclusive).
        Returns:
        The custom persistent highlights array. Can be null if no custom persistent highlight intersects the given offsets interval.
        Since:
        14.1

      • setProperties

        void setProperties​(AuthorPersistentHighlight highlight,
                   java.util.LinkedHashMap<java.lang.String,​java.lang.String> newProperties)
            throws java.lang.IllegalArgumentException
        Set new properties of a specific highlight.
        A copy of the initial properties can be obtained from AuthorPersistentHighlight.getClonedProperties()
        Parameters:
        highlight - The highlight for which the properties will be set.
        newProperties - The new highlight properties.

        Notes:
        1. Each property name must be a valid XML attribute name.
        2. Each property value will be escaped to be a valid XML attribute value.

        Throws:
        java.lang.IllegalArgumentException - Thrown when a property name is not a valid XML attribute name. The properties may not be set of the marker is in read-only content or if there is already a marker with the same properties added over the same interval.

      • setHighlightRenderer

        void setHighlightRenderer​(PersistentHighlightRenderer renderer)
        Set a renderer for customizing the way that the custom persistent highlights are displayed.
        Parameters:
        renderer - The renderer defining the way in which the highlights are painted.

      • setHighlightsActionsProvider

        void setHighlightsActionsProvider​(AuthorPersistentHighlightActionsProvider provider)
        Set the provider for the actions that are available for a specific highlight. The actions are currently displayed in the persistent highlights associated callouts popup menu, but in future could be also used as actions presented for a highlight in the contextual menu of the main editing area.
        The callouts are representations of Track Changes insert and delete highlights, review comment highlights and custom review highlights in Author mode. To associate callout information to a custom highlight the AuthorCalloutsController.setCalloutsRenderingInformationProvider(CalloutsRenderingInformationProvider) method must be used.
        Parameters:
        provider - The highlights callout rendering information provider.
        Throws:
        java.lang.IllegalArgumentException - Thrown when a property name is not a valid XML attribute name.
        Since:
        14