Mercurial > projects > dwt-mac

comparison dwt/custom/StyledTextContent.d @ 0:380af2bdd8e5

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Upload of whole dwt tree
author Jacob Carlborg <doob@me.com> <jacob.carlborg@gmail.com>
date Sat, 09 Aug 2008 17:00:02 +0200
parents
children 6337764516f1
comparison
equal deleted inserted replaced
-1:000000000000 0:380af2bdd8e5
1 /*******************************************************************************
2 * Copyright (c) 2000, 2006 IBM Corporation and others.
3 * All rights reserved. This program and the accompanying materials
4 * are made available under the terms of the Eclipse Public License v1.0
5 * which accompanies this distribution, and is available at
6 * http://www.eclipse.org/legal/epl-v10.html
7 *
8 * Contributors:
9 * IBM Corporation - initial API and implementation
10 *******************************************************************************/
11 module dwt.custom;
12
13
14 /**
15 * Clients may implement the StyledTextContent interface to provide a
16 * custom store for the StyledText widget content. The StyledText widget
17 * interacts with its StyledTextContent in order to access and update
18 * the text that is being displayed and edited in the widget.
19 * A custom content implementation can be set in the widget using the
20 * StyledText.setContent API.
21 */
22 public interface StyledTextContent {
23
24 /**
25 * Called by StyledText to add itself as an Observer to content changes.
26 * See TextChangeListener for a description of the listener methods that
27 * are called when text changes occur.
28 * <p>
29 *
30 * @param listener the listener
31 * @exception IllegalArgumentException <ul>
32 * <li>ERROR_NULL_ARGUMENT when listener is null</li>
33 * </ul>
34 */
35 public void addTextChangeListener(TextChangeListener listener);
36
37 /**
38 * Return the number of characters in the content.
39 * <p>
40 *
41 * @return the number of characters in the content.
42 */
43 public int getCharCount();
44
45 /**
46 * Return the line at the given line index without delimiters.
47 * <p>
48 *
49 * @param lineIndex index of the line to return. Does not include
50 * delimiters of preceding lines. Index 0 is the first line of the
51 * content.
52 * @return the line text without delimiters
53 */
54 public String getLine(int lineIndex);
55
56 /**
57 * Return the line index at the given character offset.
58 * <p>
59 *
60 * @param offset offset of the line to return. The first character of the
61 * document is at offset 0. An offset of getLength() is valid and should
62 * answer the number of lines.
63 * @return the line index. The first line is at index 0. If the character
64 * at offset is a delimiter character, answer the line index of the line
65 * that is delimited.
66 * For example, if text = "\r\n\r\n", and delimiter = "\r\n", then:
67 * <ul>
68 * <li>getLineAtOffset(0) is 0
69 * <li>getLineAtOffset(1) is 0
70 * <li>getLineAtOffset(2) is 1
71 * <li>getLineAtOffset(3) is 1
72 * <li>getLineAtOffset(4) is 2
73 * </ul>
74 */
75 public int getLineAtOffset(int offset);
76
77 /**
78 * Return the number of lines. Should answer 1 when no text is specified.
79 * The StyledText widget relies on this behavior for drawing the cursor.
80 * <p>
81 *
82 * @return the number of lines. For example:
83 * <ul>
84 * <li> text value ==> getLineCount
85 * <li> null ==> 1
86 * <li> "" ==> 1
87 * <li> "a\n" ==> 2
88 * <li> "\n\n" ==> 3
89 * </ul>
90 */
91 public int getLineCount();
92
93 /**
94 * Return the line delimiter that should be used by the StyledText
95 * widget when inserting new lines. New lines entered using key strokes
96 * and paste operations use this line delimiter.
97 * Implementors may use System.getProperty("line.separator") to return
98 * the platform line delimiter.
99 * <p>
100 *
101 * @return the line delimiter that should be used by the StyledText widget
102 * when inserting new lines.
103 */
104 public String getLineDelimiter();
105
106 /**
107 * Return the character offset of the first character of the given line.
108 * <p>
109 * <b>NOTE:</b> When there is no text (i.e., no lines), getOffsetAtLine(0)
110 * is a valid call that should return 0.
111 * </p>
112 *
113 * @param lineIndex index of the line. The first line is at index 0.
114 * @return offset offset of the first character of the line. The first
115 * character of the document is at offset 0. The return value should
116 * include line delimiters.
117 * For example, if text = "\r\ntest\r\n" and delimiter = "\r\n", then:
118 * <ul>
119 * <li>getOffsetAtLine(0) is 0
120 * <li>getOffsetAtLine(1) is 2
121 * <li>getOffsetAtLine(2) is 8
122 * </ul>
123 */
124 public int getOffsetAtLine(int lineIndex);
125
126 /**
127 * Returns a String representing the content at the given range.
128 * <p>
129 *
130 * @param start the start offset of the text to return. Offset 0 is the
131 * first character of the document.
132 * @param length the length of the text to return
133 * @return the text at the given range
134 */
135 public String getTextRange(int start, int length);
136
137 /**
138 * Remove the specified text changed listener.
139 * <p>
140 *
141 * @param listener the listener
142 * @exception IllegalArgumentException <ul>
143 * <li>ERROR_NULL_ARGUMENT when listener is null</li>
144 * </ul>
145 */
146 public void removeTextChangeListener(TextChangeListener listener);
147
148 /**
149 * Replace the text with "newText" starting at position "start"
150 * for a length of "replaceLength".
151 * <p>
152 * Implementors have to notify the TextChangeListeners that were added
153 * using <code>addTextChangeListener</code> before and after the content
154 * is changed. A <code>TextChangingEvent</code> has to be sent to the
155 * textChanging method before the content is changed and a
156 * <code>TextChangedEvent</code> has to be sent to the textChanged method
157 * after the content has changed.
158 * The text change that occurs after the <code>TextChangingEvent</code>
159 * has been sent has to be consistent with the data provided in the
160 * <code>TextChangingEvent</code>.
161 * This data will be cached by the widget and will be used when the
162 * <code>TextChangedEvent</code> is received.
163 * <p>
164 * The <code>TextChangingEvent</code> should be set as follows:
165 * <ul>
166 * <li>event.start = start of the replaced text
167 * <li>event.newText = text that is going to be inserted or empty String
168 * if no text will be inserted
169 * <li>event.replaceCharCount = length of text that is going to be replaced
170 * <li>event.newCharCount = length of text that is going to be inserted
171 * <li>event.replaceLineCount = number of lines that are going to be replaced
172 * <li>event.newLineCount = number of new lines that are going to be inserted
173 * </ul>
174 * <b>NOTE:</b> newLineCount is the number of inserted lines and replaceLineCount
175 * is the number of deleted lines based on the change that occurs visually.
176 * For example:
177 * <ul>
178 * <li>(replaceText, newText) ==> (replaceLineCount, newLineCount)
179 * <li>("", "\n") ==> (0, 1)
180 * <li>("\n\n", "a") ==> (2, 0)
181 * <li>("a", "\n\n") ==> (0, 2)
182 * <li>("\n", "") ==> (1, 0)
183 * </ul>
184 * </p>
185 *
186 * @param start start offset of text to replace, none of the offsets include
187 * delimiters of preceding lines, offset 0 is the first character of the
188 * document
189 * @param replaceLength length of text to replace
190 * @param text text to replace
191 * @see TextChangeListener
192 */
193 public void replaceTextRange(int start, int replaceLength, String text);
194
195 /**
196 * Set text to "text".
197 * Implementors have to send a <code>TextChangedEvent</code> to the
198 * textSet method of the TextChangeListeners that were added using
199 * <code>addTextChangeListener</code>.
200 * <p>
201 *
202 * @param text the new text
203 * @see TextChangeListener
204 */
205 public void setText(String text);
206 }