001: /*******************************************************************************
002: * Copyright (c) 2000, 2005 IBM Corporation and others.
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * IBM Corporation - initial API and implementation
010: *******************************************************************************/package org.eclipse.jface.text;
011:
012: /**
013: * Slave documents are documents whose contents is defined in terms of a master
014: * document. Thus, slave documents usually reflect a projection of the master document.
015: * Slave documents are causally connected to the master document. This means, changes
016: * of the master document have immediate effect on the slave document and vice versa.
017: * <p>
018: * A slave document manager creates slave documents for given master documents, manages the
019: * life cycle of the slave documents, and keeps track of the information flow between
020: * master and slave documents. The slave document manager defines the construction rules of the
021: * slave documents in terms of the master document.</p>
022: * <p>
023: * In order to provided backward compatibility for clients of <code>ISlaveDocumentManager</code>, extension
024: * interfaces are used to provide a means of evolution. The following extension interfaces
025: * exist:
026: * <ul>
027: * <li> {@link org.eclipse.jface.text.ISlaveDocumentManagerExtension} since version 3.0 extending the protocol
028: * with an access to all managed slave document for a given master document. </li>
029: * </ul>
030: * </p>
031: *
032: * @see org.eclipse.jface.text.IDocument
033: * @since 2.1
034: */
035: public interface ISlaveDocumentManager {
036:
037: /**
038: * Creates a new slave document for the given master document. The slave document
039: * is causally connected to its master document until <code>freeSlaveDocument</code>
040: * is called. The connection between the newly created slave document and the master
041: * document is managed by this slave document manager.
042: *
043: * @param master the master document
044: * @return the newly created slave document
045: * @see #freeSlaveDocument(IDocument)
046: */
047: IDocument createSlaveDocument(IDocument master);
048:
049: /**
050: * Frees the given slave document. If the given document is not a slave document known
051: * to this slave document manager, this call does not have any effect. A slave
052: * document is known to this slave document manager if it has been created by
053: * this manager using <code>createSlaveDocument</code>.
054: *
055: * @param slave the slave document to be freed
056: * @see #createSlaveDocument(IDocument)
057: */
058: void freeSlaveDocument(IDocument slave);
059:
060: /**
061: * Creates a new document information mapping between the given slave document and
062: * its master document. Returns <code>null</code> if the given document is unknown
063: * to this slave document manager.
064: *
065: * @param slave the slave document
066: * @return a document information mapping between the slave document and its master document or
067: * <code>null</code>
068: */
069: IDocumentInformationMapping createMasterSlaveMapping(IDocument slave);
070:
071: /**
072: * Returns the master document of the given slave document or <code>null</code> if the
073: * given document is unknown to this slave document manager.
074: *
075: * @param slave the slave document
076: * @return the master document of the given slave document or <code>null</code>
077: */
078: IDocument getMasterDocument(IDocument slave);
079:
080: /**
081: * Returns whether the given document is a slave document known to this slave document manager. A slave document
082: * is known to this slave document manager, if the document has been created by this manager.
083: *
084: * @param document the document to be checked whether it is a slave document known to this manager
085: * @return <code>true</code> if the document is a slave document, <code>false</code> otherwise
086: */
087: boolean isSlaveDocument(IDocument document);
088:
089: /**
090: * Sets the given slave document's auto expand mode. In auto expand mode, a
091: * slave document is automatically adapted to reflect all changes applied to it's master document.
092: * Assume a master document contains 30 lines and the slave is defined to contain the lines 11-20.
093: * In auto expand mode, when the master document is changed at line 8, the slave document is expanded
094: * to contain the lines 8-20.<p>
095: * This call is without effect if the given document is unknown to this slave document manager.
096: *
097: * @param slave the slave whose auto expand mode should be set
098: * @param autoExpand <code>true</code> for auto expand, <code>false</code> otherwise
099: */
100: void setAutoExpandMode(IDocument slave, boolean autoExpand);
101: }
|