| /******************************************************************************* |
| * 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.document; |
| |
| import org.eclipse.core.runtime.IAdaptable; |
| import org.eclipse.jface.text.IDocument; |
| import org.eclipse.jface.text.IDocumentExtension; |
| import org.eclipse.jface.text.IDocumentListener; |
| import org.eclipse.jface.text.Position; |
| import org.eclipse.wst.sse.core.internal.encoding.EncodingMemento; |
| import org.eclipse.wst.sse.core.internal.provisional.events.NewDocumentEvent; |
| import org.eclipse.wst.sse.core.internal.provisional.events.StructuredDocumentEvent; |
| import org.eclipse.wst.sse.core.internal.provisional.text.IStructuredDocumentRegion; |
| import org.eclipse.wst.sse.core.internal.provisional.text.IStructuredDocumentRegionList; |
| |
| |
| /** |
| * A IStructuredDocument is a collection of StructuredDocumentRegions. It's |
| * often called a "flat model" because its does contain some structural |
| * information, but not very much, usually, at most, a few levels of |
| * containment. |
| * |
| * Clients should not implement. |
| * |
| * @plannedfor 1.0 |
| */ |
| public interface IStructuredDocumentProposed extends IDocument, IDocumentExtension, IAdaptable { |
| |
| /** |
| * The document changing listeners receives the same events as the |
| * document listeners, but the difference is the timing and |
| * synchronization of data changes and notifications. |
| */ |
| void addDocumentChangingListener(IDocumentListener 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); |
| |
| /** |
| * Returns the region contained by offset. |
| * |
| * @param offset |
| * @return |
| */ |
| IStructuredDocumentRegion getRegionAtCharacterOffset(int offset); |
| |
| /** |
| * Resturns a list of the structured document regions. |
| * |
| * Note: possibly expensive call, not to be used casually. |
| * |
| * @return a list of the structured document regions. |
| */ |
| IStructuredDocumentRegionList getRegionList(); |
| |
| |
| /** |
| * Returns the text of this document. |
| * |
| * Same as 'get' in super class, added for descriptiveness. |
| * |
| * @return the text of this document. |
| */ |
| String getText(); |
| |
| /** |
| * 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. |
| */ |
| IStructuredDocumentProposed newInstance(); |
| |
| /** |
| * The document changing listeners receives the same events as the |
| * document listeners, but the difference is the timing and |
| * synchronization of data changes and notifications. |
| */ |
| void removeDocumentChangingListener(IDocumentListener 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. |
| * |
| * Similar to 'replace' in super class. |
| */ |
| StructuredDocumentEvent replaceText(Object requester, int oldStart, int replacementLength, String requestedChange); |
| |
| /** |
| * Note, same as replaceText API, but will allow readonly areas to be |
| * replaced. This method is not to be called by clients, only |
| * infrastructure. For example, 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. There might be other cases |
| * where its used to give the user a choice, e.g. "you are about to |
| * overwrite read only portions, do you want to continue". |
| */ |
| StructuredDocumentEvent overrideReadOnlyreplaceText(Object requester, int oldStart, int replacementLength, String requestedChange); |
| |
| /** |
| * One of the APIs to manipulate the IStructuredDocument in terms of Text. |
| * |
| * The setText method replaces all text in the model. |
| * |
| * @param requester - |
| * the object requesting the document be created. |
| * @param allText - |
| * all the text of the document. |
| * @return NewDocumentEvent - besides causing this event to be sent to |
| * document listeners, the event is returned. |
| */ |
| NewDocumentEvent setText(Object requester, String allText); |
| |
| /** |
| * Returns the encoding memento for this document. |
| * |
| * @return the encoding memento for this document. |
| */ |
| EncodingMemento getEncodingMemento(); |
| |
| /** |
| * Returns the line delimiter detected when this document was read from |
| * storage. |
| * |
| * @return line delimiter detected when this document was read from |
| * storage. |
| */ |
| String getDetectedLineDelimiter(); |
| |
| /** |
| * Sets the encoding memento for this document. |
| * |
| * Is not to be called by clients, only document creation classes. |
| * |
| * @param localEncodingMemento |
| */ |
| void setEncodingMemento(EncodingMemento localEncodingMemento); |
| |
| /** |
| * Sets the detected line delimiter when the document was read. Is not to |
| * be called by clients, only document creation classes. |
| * |
| * @param probableLineDelimiter |
| */ |
| void setDetectedLineDelimiter(String probableLineDelimiter); |
| |
| /** |
| * This function provides a way for clients to compare a string with a |
| * region of the documnet, without having to retrieve (create) a string |
| * from the document, thus more efficient of lots of comparisons being |
| * done. |
| * |
| * @param ignoreCase - |
| * if true the characters are compared based on identity. If |
| * false, the string are compared with case accounted for. |
| * @param testString - |
| * the string to compare. |
| * @param documentOffset - |
| * the document in the offset to start the comparison. |
| * @param length - |
| * the length in the document to compare (Note: technically, |
| * clients could just provide the string, and we could infer |
| * the length from the string supplied, but this leaves every |
| * client to correctly not even ask us if the the string length |
| * doesn't match the expected length, so this is an effort to |
| * maximize performance with correct code. |
| * @return true if matches, false otherwise. |
| */ |
| boolean stringMatches(boolean ignoreCase, String testString, int documentOffset, int length); |
| |
| Position createPosition(int offset, String category, String type); |
| |
| Position createPosition(int offset, int length, String category, String type); |
| |
| } |