Package org.eclipse.jface.text.link

Class LinkedModeModel

  • public class LinkedModeModel
extends Object
    The model for linked mode, umbrellas several LinkedPositionGroups. Once installed, the model propagates any changes to a position to all its siblings in the same position group.

    Setting up a model consists of first adding LinkedPositionGroups to it, and then installing the model by either calling forceInstall() or tryInstall(). After installing the model, it becomes sealed and no more groups may be added.

    If a document change occurs that would modify more than one position group or that would invalidate the disjointness requirement of the positions, the model is torn down and all positions are deleted. The same happens upon calling exit(int).

    Nesting

    A LinkedModeModel may be nested into another model. This happens when installing a model the positions of which all fit into a single position in a parent model that has previously been installed on the same document(s).

    Clients may instantiate instances of this class.

    Since:
    3.0
    Restriction:
    This class is not intended to be subclassed by clients.

    • Constructor Detail

      • LinkedModeModel

        public LinkedModeModel()
        Creates a new model.
        Since:
        3.1

    • Method Detail

      • hasInstalledModel

        public static boolean hasInstalledModel​(IDocument document)
        Checks whether there is already a model installed on document.
        Parameters:
        document - the IDocument of interest
        Returns:
        true if there is an existing model, false otherwise

      • hasInstalledModel

        public static boolean hasInstalledModel​(IDocument[] documents)
        Checks whether there is already a linked mode model installed on any of the documents.
        Parameters:
        documents - the IDocuments of interest
        Returns:
        true if there is an existing model, false otherwise

      • closeAllModels

        public static void closeAllModels​(IDocument document)
        Cancels any linked mode model on the specified document. If there is no model, nothing happens.
        Parameters:
        document - the document whose LinkedModeModel should be canceled

      • getModel

        public static LinkedModeModel getModel​(IDocument document,
                                       int offset)
        Returns the model currently active on document at offset, or null if there is none.
        Parameters:
        document - the document for which the caller asks for a model
        offset - the offset into document, as there may be several models on a document
        Returns:
        the model currently active on document, or null

      • exit

        public void exit​(int flags)
        Causes this model to exit. Called either if an illegal document change is detected, or by the UI.
        Parameters:
        flags - the exit flags as defined in ILinkedModeListener

      • stopForwarding

        public void stopForwarding​(int flags)
        Causes this model to stop forwarding updates. The positions are not unregistered however, which will only happen when exit is called, or after the next document change.
        Parameters:
        flags - the exit flags as defined in ILinkedModeListener
        Since:
        3.1

      • addGroup

        public void addGroup​(LinkedPositionGroup group)
              throws BadLocationException
        Adds a position group to this LinkedModeModel. This method may not be called if the model has been installed. Also, if a UI has been set up for this model, it may not pick up groups added afterwards.

        If the positions in group conflict with any other group in this model, a BadLocationException is thrown. Also, if this model is nested inside another one, all positions in all groups of the child model have to reside within a single position in the parent model, otherwise a BadLocationException is thrown.

        If group already exists, nothing happens.

        Parameters:
        group - the group to be added to this model
        Throws:
        BadLocationException - if the group conflicts with the other groups in this model or violates the nesting requirements.
        IllegalStateException - if the method is called when the model is already sealed

      • forceInstall

        public void forceInstall()
                  throws BadLocationException
        Installs this model, which includes registering as document listener on all involved documents and storing global information about this model. Any conflicting model already present will be closed.

        If an exception is thrown, the installation failed and the model is unusable.

        Throws:
        BadLocationException - if some of the positions of this model were not valid positions on their respective documents

      • tryInstall

        public boolean tryInstall()
                   throws BadLocationException
        Installs this model, which includes registering as document listener on all involved documents and storing global information about this model. If there is another model installed on the document(s) targeted by the receiver that conflicts with it, installation may fail.

        The return value states whether installation was successful; if not, the model is not installed and will not work.

        Returns:
        true if installation was successful, false otherwise
        Throws:
        BadLocationException - if some of the positions of this model were not valid positions on their respective documents

      • isNested

        public boolean isNested()
        Returns whether this model is nested.

        This method is part of the private protocol between LinkedModeUI and LinkedModeModel.

        Returns:
        true if this model is nested, false otherwise

      • getTabStopSequence

        public List<LinkedPosition> getTabStopSequence()
        Returns the positions in this model that have a tab stop, in the order they were added.

        This method is part of the private protocol between LinkedModeUI and LinkedModeModel.

        Returns:
        the positions in this model that have a tab stop, in the order they were added

      • addLinkingListener

        public void addLinkingListener​(ILinkedModeListener listener)
        Adds listener to the set of listeners that are informed upon state changes.
        Parameters:
        listener - the new listener

      • removeLinkingListener

        public void removeLinkingListener​(ILinkedModeListener listener)
        Removes listener from the set of listeners that are informed upon state changes.
        Parameters:
        listener - the new listener

      • findPosition

        public LinkedPosition findPosition​(LinkedPosition toFind)
        Finds the position in this model that is closest after toFind. toFind needs not be a position in this model and serves merely as an offset.

        This method part of the private protocol between LinkedModeUI and LinkedModeModel.

        Parameters:
        toFind - the position to search from
        Returns:
        the closest position in the same document as toFind after the offset of toFind, or null

      • anyPositionContains

        public boolean anyPositionContains​(int offset)
        Returns whether an offset is contained by any position in this model.
        Parameters:
        offset - the offset to check
        Returns:
        true if offset is included by any position (see LinkedPosition.includes(int)) in this model, false otherwise

      • getGroupForPosition

        public LinkedPositionGroup getGroupForPosition​(Position position)
        Returns the linked position group that contains position, or null if position is not contained in any group within this model. Group containment is tested by calling group.contains(position) for every group in this model.

        This method part of the private protocol between LinkedModeUI and LinkedModeModel.

        Parameters:
        position - the position the group of which is requested
        Returns:
        the first group in this model for which group.contains(position) returns true, or null if no group contains position