ISlaveDocumentManager


1   /*******************************************************************************
2    * Copyright (c) 2000, 2005 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    *
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   *******************************************************************************/
11  
12  package org.eclipse.jface.text;
13  
14  /**
15   * Slave documents are documents whose contents is defined in terms of a master
16   * document. Thus, slave documents usually reflect a projection of the master document.
17   * Slave documents are causally connected to the master document. This means, changes
18   * of the master document have immediate effect on the slave document and vice versa.
19   * <p>
20   * A slave document manager creates slave documents for given master documents, manages the
21   * life cycle of the slave documents, and keeps track of the information flow between
22   * master and slave documents. The slave document manager defines the construction rules of the
23   * slave documents in terms of the master document.</p>
24   * <p>
25  * In order to provided backward compatibility for clients of <code>ISlaveDocumentManager</code>, extension
26   * interfaces are used to provide a means of evolution. The following extension interfaces
27   * exist:
28   * <ul>
29   * <li> {@link org.eclipse.jface.text.ISlaveDocumentManagerExtension} since version 3.0 extending the protocol
30   *      with an access to all managed slave document for a given master document. </li>
31   * </ul>
32   * </p>
33   *
34   * @see org.eclipse.jface.text.IDocument
35   * @since 2.1
36   */
37  public interface ISlaveDocumentManager {
38  
39      /**
40       * Creates a new slave document for the given master document. The slave document
41       * is causally connected to its master document until <code>freeSlaveDocument</code>
42       * is called. The connection between the newly created slave document and the master
43       * document is managed by this slave document manager.
44       *
45       * @param master the master document
46       * @return the newly created slave document
47       * @see #freeSlaveDocument(IDocument)
48       */
49      IDocument createSlaveDocument(IDocument master);
50  
51      /**
52       * Frees the given slave document. If the given document is not a slave document known
53       * to this slave document manager, this call does not have any effect. A slave
54       * document is known to this slave document manager if it has been created by
55       * this manager using <code>createSlaveDocument</code>.
56       *
57       * @param slave the slave document to be freed
58       * @see #createSlaveDocument(IDocument)
59       */
60      void freeSlaveDocument(IDocument slave);
61  
62      /**
63       * Creates a new document information mapping between the given slave document and
64       * its master document. Returns <code>null</code> if the given document is unknown
65       * to this slave document manager.
66       *
67       * @param slave the slave document
68       * @return a document information mapping between the slave document and its master document or
69       *      <code>null</code>
70       */
71      IDocumentInformationMapping createMasterSlaveMapping(IDocument slave);
72  
73      /**
74       * Returns the master document of the given slave document or <code>null</code> if the
75       * given document is unknown to this slave document manager.
76       *
77       * @param slave the slave document
78       * @return the master document of the given slave document or <code>null</code>
79       */
80      IDocument getMasterDocument(IDocument slave);
81  
82      /**
83       * Returns whether the given document is a slave document known to this slave document manager. A slave document
84       * is known to this slave document manager, if the document has been created by this manager.
85       *
86       * @param document the document to be checked whether it is a slave document known to this manager
87       * @return <code>true</code> if the document is a slave document, <code>false</code> otherwise
88       */
89      boolean isSlaveDocument(IDocument document);
90  
91      /**
92       * Sets the given slave document's auto expand mode. In auto expand mode, a
93       * slave document is automatically adapted to reflect all changes applied to it's master document.
94       * Assume a master document contains 30 lines and the slave is defined to contain the lines 11-20.
95       * In auto expand mode, when the master document is changed at line 8, the slave document is expanded
96       * to contain the lines 8-20.<p>
97       * This call is without effect if the given document is unknown to this slave document manager.
98       *
99       * @param slave the slave whose auto expand mode should be set
100      * @param autoExpand <code>true</code> for auto expand, <code>false</code> otherwise
101      */
102     void setAutoExpandMode(IDocument slave, boolean autoExpand);
103 }
104
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags