| /****************************************************************************** |
| * Copyright (c) 2000, 2005 IBM Corporation and others. |
| * All rights reserved. This program and the accompanying materials |
| * are made available under the terms of the Eclipse Public License v1.0 |
| * which accompanies this distribution, and is available at |
| * http://www.eclipse.org/legal/epl-v10.html |
| * |
| * Contributors: |
| * IBM Corporation - initial API and implementation |
| ****************************************************************************/ |
| |
| package org.eclipse.gmf.runtime.diagram.ui.resources.editor.document; |
| |
| /** |
| * An <code>IDocument</code> represents extensible content providing support |
| * |
| * A document allows to set its content and to manipulate it. |
| * On each document change, all registered document listeners are informed exactly once. |
| * |
| * @see org.eclipse.gmf.runtime.diagram.ui.resources.editor.document.IDocumentListener |
| */ |
| public interface IDocument { |
| /** |
| * The unknown modification stamp. |
| */ |
| long UNKNOWN_MODIFICATION_STAMP= -1; |
| |
| /** |
| * Returns the modification stamp of this document. The modification stamp |
| * is updated each time a modifying operation is called on this document. If |
| * two modification stamps of the same document are identical then the document |
| * content is too, however, same content does not imply same modification stamp. |
| * <p> |
| * The magnitude or sign of the numerical difference between two modification stamps |
| * is not significant. |
| * </p> |
| * |
| * @return the modification stamp of this document or <code>UNKNOWN_MODIFICATION_STAMP</code> |
| */ |
| long getModificationStamp(); |
| |
| /** |
| * Registers the document listener with the document. After registration |
| * the IDocumentListener is informed about each change of this document. |
| * If the listener is already registered nothing happens.<p> |
| * An <code>IDocumentListener</code> may call back to this method |
| * when being inside a document notification. |
| * |
| * @param listener the listener to be registered |
| */ |
| void addDocumentListener(IDocumentListener listener); |
| |
| /** |
| * Removes the listener from the document's list of document listeners. |
| * If the listener is not registered with the document nothing happens.<p> |
| * An <code>IDocumentListener</code> may call back to this method |
| * when being inside a document notification. |
| * |
| * @param listener the listener to be removed |
| */ |
| void removeDocumentListener(IDocumentListener listener); |
| |
| /** |
| * Adds the given document listener as one which is notified before |
| * those document listeners added with <code>addDocumentListener</code> |
| * are notified. If the given listener is also registered using |
| * <code>addDocumentListener</code> it will be notified twice. |
| * If the listener is already registered nothing happens.<p> |
| * |
| * This method is not for public use. |
| * |
| * @param documentAdapter the listener to be added as pre-notified document listener |
| * |
| * @see #removePrenotifiedDocumentListener(IDocumentListener) |
| */ |
| void addPrenotifiedDocumentListener(IDocumentListener documentAdapter); |
| |
| /** |
| * Removes the given document listener from the document's list of |
| * pre-notified document listeners. If the listener is not registered |
| * with the document nothing happens. <p> |
| * |
| * This method is not for public use. |
| * |
| * @param documentAdapter the listener to be removed |
| * |
| * @see #addPrenotifiedDocumentListener(IDocumentListener) |
| */ |
| void removePrenotifiedDocumentListener(IDocumentListener documentAdapter); |
| |
| /** |
| * Returns this document's contents. |
| * |
| * @return the document's contents |
| */ |
| Object getContent(); |
| |
| /** |
| * Replaces the content of the document with the given content. |
| * Sends a <code>DocumentEvent</code> to all registered <code>IDocumentListener</code>. |
| * |
| * @param documentContent the new content of the document |
| * |
| * @see DocumentEvent |
| * @see IDocumentListener |
| */ |
| void setContent(Object documentContent); |
| |
| /** |
| * Replaces the content of the document with the given text. |
| * Sends a <code>DocumentEvent</code> to all registered <code>IDocumentListener</code>. |
| * |
| * @param content the new content of the document |
| * @param modificationStamp of the document after setting the content |
| * |
| * @see DocumentEvent |
| * @see IDocumentListener |
| */ |
| void setContent(Object content, long modificationStamp); |
| |
| /** |
| * The affect of these calls is that no document listener is notified |
| * until <code>resumeListenerNotification</code> is called. This allows clients |
| * to update structure before any listener is informed about the change.<p> |
| * Listener notification can only be stopped for a single <code>replace</code> operation. |
| * Otherwise, document change notifications will be lost. |
| */ |
| void stopListenerNotification(); |
| |
| /** |
| * Resumes the notification of document listeners which must previously |
| * have been stopped by a call to <code>stopListenerNotification</code>. |
| */ |
| void resumeListenerNotification(); |
| } |