1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
|
/*******************************************************************************
* 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.
*
* @deprecated - was never used
*/
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);
}
|
