KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > swt > custom > StyledTextContent


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 package org.eclipse.swt.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 JavaDoc 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) == 0
69  * <li>getLineAtOffset(1) == 0
70  * <li>getLineAtOffset(2) == 1
71  * <li>getLineAtOffset(3) == 1
72  * <li>getLineAtOffset(4) == 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 JavaDoc 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) == 0
120  * <li>getOffsetAtLine(1) == 2
121  * <li>getOffsetAtLine(2) == 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 JavaDoc 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 JavaDoc 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 JavaDoc text);
206 }
207
Popular Tags