/*******************************************************************************
* 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);
}