| /******************************************************************************* |
| * Copyright (c) 2001, 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 |
| * Jens Lukowski/Innoopract - initial renaming/restructuring |
| * |
| *******************************************************************************/ |
| package org.eclipse.wst.sse.core.internal.provisional.text; |
| |
| import org.eclipse.core.runtime.IAdaptable; |
| import org.eclipse.jface.text.IDocumentExtension; |
| import org.eclipse.wst.sse.core.internal.encoding.EncodingMemento; |
| import org.eclipse.wst.sse.core.internal.ltk.parser.RegionParser; |
| import org.eclipse.wst.sse.core.internal.provisional.document.IEncodedDocument; |
| import org.eclipse.wst.sse.core.internal.provisional.events.IModelAboutToBeChangedListener; |
| import org.eclipse.wst.sse.core.internal.provisional.events.IStructuredDocumentListener; |
| import org.eclipse.wst.sse.core.internal.provisional.events.StructuredDocumentEvent; |
| import org.eclipse.wst.sse.core.internal.undo.IStructuredTextUndoManager; |
| |
| |
| /** |
| * A IStructuredDocument is a collection of StructuredDocumentRegions. It's |
| * often called "flat" because its contents by design do not contain much |
| * structural information beyond containment. Clients should not implement. |
| */ |
| public interface IStructuredDocument extends IEncodedDocument, IDocumentExtension, IAdaptable { |
| |
| void addDocumentAboutToChangeListener(IModelAboutToBeChangedListener listener); |
| |
| /** |
| * The StructuredDocumentListeners and ModelChangedListeners are very |
| * similar. They both receive identical events. The difference is the |
| * timing. The "pure" StructuredDocumentListeners are notified after the |
| * structuredDocument has been changed, but before other, related models |
| * may have been changed such as the Structural Model. The Structural |
| * model is in fact itself a "pure" StructuredDocumentListner. The |
| * ModelChangedListeners can rest assured that all models and data have |
| * been updated from the change by the tiem they are notified. This is |
| * especially important for the text widget, for example, which may rely |
| * on both structuredDocument and structural model information. |
| */ |
| void addDocumentChangedListener(IStructuredDocumentListener listener); |
| |
| /** |
| * The StructuredDocumentListeners and ModelChangedListeners are very |
| * similar. They both receive identical events. The difference is the |
| * timing. The "pure" StructuredDocumentListeners are notified after the |
| * structuredDocument has been changed, but before other, related models |
| * may have been changed such as the Structural Model. The Structural |
| * model is in fact itself a "pure" StructuredDocumentListner. The |
| * ModelChangedListeners can rest assured that all models and data have |
| * been updated from the change by the tiem they are notified. This is |
| * especially important for the text widget, for example, which may rely |
| * on both structuredDocument and structural model information. |
| */ |
| void addDocumentChangingListener(IStructuredDocumentListener listener); |
| |
| /** |
| * this API ensures that any portion of the document within startOff to |
| * length is not readonly (that is, that its editable). Note that if the |
| * range overlaps with other readonly regions, those other readonly |
| * regions will be adjusted. |
| * |
| * @param startOffset |
| * @param length |
| */ |
| void clearReadOnly(int startOffset, int length); |
| |
| /** |
| * returns true if any portion of startOffset to length is readonly |
| * |
| * @param startOffset |
| * @param length |
| * @return |
| */ |
| boolean containsReadOnly(int startOffset, int length); |
| |
| /** |
| * This method is to remember info about the encoding When the resource |
| * was last loaded or saved. Note: it is not kept "current", that is, can |
| * not be depended on blindly to reflect what encoding to use. For that, |
| * must go through the normal rules expressed in Loaders and Dumpers. |
| */ |
| |
| EncodingMemento getEncodingMemento(); |
| |
| org.eclipse.wst.sse.core.internal.provisional.text.IStructuredDocumentRegion getFirstStructuredDocumentRegion(); |
| |
| org.eclipse.wst.sse.core.internal.provisional.text.IStructuredDocumentRegion getLastStructuredDocumentRegion(); |
| |
| /** |
| * This can be considered the preferred delimiter. |
| */ |
| public String getLineDelimiter(); |
| |
| int getLineOfOffset(int offset); // throws SourceEditingException; |
| |
| /** |
| * The parser is now required on constructor, so there are occasions it |
| * needs to be retrieved, such as to be initialized by EmbeddedContentType |
| */ |
| RegionParser getParser(); |
| |
| /** |
| * @deprecated use getStructuredDocumentRegions() |
| * @return |
| */ |
| IStructuredDocumentRegionList getRegionList(); |
| |
| /** |
| * Returns the <code>IStructuredDocumentRegion</code> at the given character offset. |
| * @param offset |
| * @return the <code>IStructuredDocumentRegion</code> at the given character offset. |
| */ |
| IStructuredDocumentRegion getRegionAtCharacterOffset(int offset); |
| |
| /** |
| * Returns <code>IStructuredDocumentRegion</code>s in the specified range. |
| * @param offset |
| * @param length |
| * @return <code>IStructuredDocumentRegion</code>s in the specified range. |
| */ |
| IStructuredDocumentRegion[] getStructuredDocumentRegions(int offset, int length); |
| |
| /** |
| * Returns all <code>IStructuredDocumentRegion</code>s in the document. |
| * @return all <code>IStructuredDocumentRegion</code>s in the document. |
| */ |
| IStructuredDocumentRegion[] getStructuredDocumentRegions(); |
| |
| /** |
| * Note: this method was made public, and part of the interface, for |
| * easier testing. Clients normally never manipulate the reparser directly |
| * (nor should they need to). |
| */ |
| IStructuredTextReParser getReParser(); |
| |
| String getText(); |
| |
| IStructuredTextUndoManager getUndoManager(); |
| |
| /** |
| * causes that portion of the document from startOffset to length to be |
| * marked as readonly. Note that if this range overlaps with some other |
| * region with is readonly, the regions are effectivly combined. |
| * |
| * @param startOffset |
| * @param length |
| */ |
| void makeReadOnly(int startOffset, int length); |
| |
| /** |
| * newInstance is similar to clone, except it contains no data. One |
| * important thing to duplicate is the parser, with the parser correctly |
| * "cloned", including its tokeninzer, block tags, etc. |
| * |
| * NOTE: even after obtaining a 'newInstance' the client may have to do |
| * some initialization, for example, it may need to add its own model |
| * listeners. Or, as another example, if the IStructuredDocument has a |
| * parser of type StructuredDocumentRegionParser, then the client may need |
| * to add its own StructuredDocumentRegionHandler to that parser, if it is |
| * in fact needed. |
| */ |
| IStructuredDocument newInstance(); |
| |
| void removeDocumentAboutToChangeListener(IModelAboutToBeChangedListener listener); |
| |
| void removeDocumentChangedListener(IStructuredDocumentListener listener); |
| |
| void removeDocumentChangingListener(IStructuredDocumentListener listener); |
| |
| /** |
| * One of the APIs to manipulate the IStructuredDocument. |
| * |
| * replaceText replaces the text from oldStart to oldEnd with the new text |
| * found in the requestedChange string. If oldStart and oldEnd are equal, |
| * it is an insertion request. If requestedChange is null (or empty) it is |
| * a delete request. Otherwise it is a replace request. |
| */ |
| StructuredDocumentEvent replaceText(Object source, int oldStart, int replacementLength, String requestedChange); |
| |
| /** |
| * Note, same as replaceText API, but will allow readonly areas to be |
| * replaced. This should seldom be called with a value of "true" for |
| * ignoreReadOnlySetting. One case where its ok is with undo operations |
| * (since, presumably, if user just did something that happended to |
| * involve some inserting readonly text, they should normally be allowed |
| * to still undo that operation. Otherwise, I can't think of a single |
| * example, unless its to give the user a choice, e.g. "you are about to |
| * overwrite read only portions, do you want to continue". |
| */ |
| StructuredDocumentEvent replaceText(Object source, int oldStart, int replacementLength, String requestedChange, boolean ignoreReadOnlySetting); |
| |
| /** |
| * This method is to remember info about the encoding When the resource |
| * was last loaded or saved. Note: it is not kept "current", that is, can |
| * not be depended on blindly to reflect what encoding to use. For that, |
| * must go through the normal rules expressed in Loaders and Dumpers. |
| */ |
| void setEncodingMemento(EncodingMemento encodingMemento); |
| |
| public void setLineDelimiter(String delimiter); |
| |
| /** |
| * One of the APIs to manipulate the IStructuredDocument in terms of Text. |
| * |
| * The setText method replaces all text in the model. |
| */ |
| StructuredDocumentEvent setText(Object requester, String allText); |
| |
| void setUndoManager(IStructuredTextUndoManager undoManager); |
| |
| } |