bundles/org.eclipse.wst.sse.core/src/org/eclipse/wst/sse/core/internal/provisional/text/IStructuredDocument.java - sourceediting/webtools.sourceediting - Git at Google

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

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

	}