KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > jface > contentassist > IContentAssistSubjectControl


1 /*******************************************************************************
2  * Copyright (c) 2000, 2005 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.jface.contentassist;
12
13 import org.eclipse.swt.custom.VerifyKeyListener;
14 import org.eclipse.swt.events.KeyListener;
15 import org.eclipse.swt.events.SelectionListener;
16 import org.eclipse.swt.graphics.Point;
17 import org.eclipse.swt.widgets.Control;
18
19 import org.eclipse.jface.text.IDocument;
20 import org.eclipse.jface.text.IEventConsumer;
21
22
23 /**
24  * A content assist subject control can request assistance provided by a
25  * {@linkplain org.eclipse.jface.contentassist.ISubjectControlContentAssistant subject control content assistant}.
26  *
27  * @since 3.0
28  */
29 public interface IContentAssistSubjectControl {
30
31     /**
32      * Returns the control of this content assist subject control.
33      *
34      * @return the control of this content assist subject control
35      */
36     Control getControl();
37
38     /**
39      * Returns the line height.
40      *
41      * @return line height in pixel
42      * @exception org.eclipse.swt.SWTException
43      * <ul>
44      * <li>{@link org.eclipse.swt.SWT#ERROR_WIDGET_DISPOSED} - if the receiver has been
45      * disposed</li>
46      * <li>{@link org.eclipse.swt.SWT#ERROR_THREAD_INVALID_ACCESS} - if not called from the
47      * thread that created the receiver</li>
48      * </ul>
49      */
50     int getLineHeight();
51
52     /**
53      * Returns the caret position relative to the start of the text in widget
54      * coordinates.
55      *
56      * @return the caret position relative to the start of the text in widget
57      * coordinates
58      * @exception org.eclipse.swt.SWTException
59      * <ul>
60      * <li>{@link org.eclipse.swt.SWT#ERROR_WIDGET_DISPOSED} - if the receiver has been
61      * disposed</li>
62      * <li>{@link org.eclipse.swt.SWT#ERROR_THREAD_INVALID_ACCESS} - if not called from the
63      * thread that created the receiver</li>
64      * </ul>
65      */
66     int getCaretOffset();
67
68     /**
69      * Returns the x, y location of the upper left corner of the character
70      * bounding box at the specified offset in the text. The point is relative
71      * to the upper left corner of the widget client area.
72      *
73      * @param offset widget offset relative to the start of the content 0
74      * <= offset <= getCharCount()
75      * @return x, y location of the upper left corner of the character bounding
76      * box at the specified offset in the text
77      * @exception org.eclipse.swt.SWTException
78      * <ul>
79      * <li>{@link org.eclipse.swt.SWT#ERROR_WIDGET_DISPOSED} - if the receiver has been disposed</li>
80      * <li>{@link org.eclipse.swt.SWT#ERROR_THREAD_INVALID_ACCESS} - if not called from the thread that created the receiver</li>
81      * </ul>
82      * @exception IllegalArgumentException when the offset is outside the valid range
83      */
84     Point getLocationAtOffset(int offset);
85
86     /**
87      * Returns the line delimiter used for entering new lines by key down or
88      * paste operation.
89      *
90      * @return line delimiter used for entering new lines by key down or paste
91      * operation
92      * @exception org.eclipse.swt.SWTException
93      * <ul>
94      * <li>{@link org.eclipse.swt.SWT#ERROR_WIDGET_DISPOSED} - if the receiver has been disposed</li>
95      * <li>{@link org.eclipse.swt.SWT#ERROR_THREAD_INVALID_ACCESS} - if not called from the thread that created the receiver</li>
96      * </ul>
97      */
98     String JavaDoc getLineDelimiter();
99
100     /**
101      * Returns the selected range in the subject's widget.
102      *
103      * @return start and length of the selection, x is the offset of the
104      * @exception org.eclipse.swt.SWTException
105      * <ul>
106      * <li>{@link org.eclipse.swt.SWT#ERROR_WIDGET_DISPOSED} - if the receiver has been disposed</li>
107      * <li>{@link org.eclipse.swt.SWT#ERROR_THREAD_INVALID_ACCESS} - if not called from the thread that created the receiver</li>
108      * </ul>
109      */
110     Point getWidgetSelectionRange();
111
112     /**
113      * Returns the selected range.
114      *
115      * @return start and length of the selection, x is the offset and y the
116      * length based on the subject's model (e.g. document)
117      */
118     Point getSelectedRange();
119
120     /**
121      * Sets the selected range. Offset and length based on the subject's
122      * model (e.g. document).
123      *
124      * @param offset the offset of the selection based on the subject's model e.g. document
125      * @param length the length of the selection based on the subject's model e.g. document
126      */
127     void setSelectedRange(int offset, int length);
128
129     /**
130      * Reveals the given region. Offset and length based on the subject's
131      * model (e.g. document).
132      *
133      * @param offset the offset of the selection based on the subject's model e.g. document
134      * @param length the length of the selection based on the subject's model e.g. document
135      */
136     void revealRange(int offset, int length);
137
138     /**
139      * Returns this content assist subject control's document.
140      *
141      * @return the viewer's input document
142      */
143     IDocument getDocument();
144
145     /**
146      * If supported, appends a verify key listener to the viewer's list of verify key
147      * listeners. If the listener is already registered with the viewer this
148      * call moves the listener to the end of the list.
149      * <p>
150      * Note: This content assist subject control may not support appending a verify
151      * listener, in which case <code>false</code> will be returned. If this
152      * content assist subject control only supports <code>addVerifyKeyListener</code>
153      * then this method can be used but <code>prependVerifyKeyListener</code>
154      * must return <code>false</code>.
155      * </p>
156      *
157      * @param verifyKeyListener the listener to be added
158      * @return <code>true</code> if the listener was added
159      */
160     boolean appendVerifyKeyListener(VerifyKeyListener verifyKeyListener);
161
162     /**
163      * If supported, inserts the verify key listener at the beginning of this content assist
164      * subject's list of verify key listeners. If the listener is already
165      * registered with the viewer this call moves the listener to the beginning
166      * of the list.
167      * <p>
168      * Note: This content assist subject control may not support prepending a verify
169      * listener, in which case <code>false</code> will be returned. However,
170      * {@link #appendVerifyKeyListener(VerifyKeyListener)} might work.
171      * </p>
172      *
173      * @param verifyKeyListener the listener to be inserted
174      * @return <code>true</code> if the listener was added
175      */
176     boolean prependVerifyKeyListener(VerifyKeyListener verifyKeyListener);
177
178     /**
179      * Removes the verify key listener from this content assist subject control's
180      * list of verify key listeners. If the listener is not registered, this
181      * call has no effect.
182      *
183      * @param verifyKeyListener the listener to be removed
184      */
185     void removeVerifyKeyListener(VerifyKeyListener verifyKeyListener);
186
187     /**
188      * Tests whether a verify key listener can be added either using <code>prependVerifyKeyListener</code>
189      * or {@link #appendVerifyKeyListener(VerifyKeyListener)}.
190      *
191      * @return <code>true</code> if adding verify key listeners is supported
192      */
193     boolean supportsVerifyKeyListener();
194
195     /**
196      * Adds the listener to the collection of listeners who will be notified
197      * when keys are pressed and released on the system keyboard, by sending it
198      * one of the messages defined in the {@link KeyListener} interface.
199      *
200      * @param keyListener the listener which should be notified
201      * @exception IllegalArgumentException if the listener is <code>null</code>
202      * @exception org.eclipse.swt.SWTException
203      * <ul>
204      * <li>{@link org.eclipse.swt.SWT#ERROR_WIDGET_DISPOSED} - if the receiver has been disposed</li>
205      * <li>{@link org.eclipse.swt.SWT#ERROR_THREAD_INVALID_ACCESS} - if not called from the thread that created the receiver</li>
206      * </ul>
207      *
208      * @see KeyListener
209      * @see #removeKeyListener(KeyListener)
210      */
211     void addKeyListener(KeyListener keyListener);
212
213     /**
214      * Removes the listener from the collection of listeners who will be
215      * notified when keys are pressed and released on the system keyboard.
216      *
217      * @param keyListener the listener which should be notified
218      * @exception IllegalArgumentException if the listener is null</li>
219      * @exception org.eclipse.swt.SWTException
220      * <ul>
221      * <li>{@link org.eclipse.swt.SWT#ERROR_WIDGET_DISPOSED} - if the receiver has been disposed</li>
222      * <li>{@link org.eclipse.swt.SWT#ERROR_THREAD_INVALID_ACCESS} - if not called from the thread that created the receiver</li>
223      * </ul>
224      * @see KeyListener
225      * @see #addKeyListener(KeyListener)
226      */
227     void removeKeyListener(KeyListener keyListener);
228
229     /**
230      * If supported, registers an event consumer with this content assist
231      * subject.
232      *
233      * @param eventConsumer the content assist subject control's event consumer. <code>null</code>
234      * is a valid argument.
235      */
236     void setEventConsumer(IEventConsumer eventConsumer);
237
238     /**
239      * Removes the specified selection listener.
240      * <p>
241      *
242      * @param selectionListener the listener
243      * @exception org.eclipse.swt.SWTException <ul>
244      * <ul>
245      * <li>{@link org.eclipse.swt.SWT#ERROR_WIDGET_DISPOSED} - if the receiver has been disposed</li>
246      * <li>{@link org.eclipse.swt.SWT#ERROR_THREAD_INVALID_ACCESS} - if not called from the thread that created the receiver</li>
247      * </ul>
248      * @exception IllegalArgumentException if listener is <code>null</code>
249      */
250     void removeSelectionListener(SelectionListener selectionListener);
251
252     /**
253      * If supported, adds a selection listener. A Selection event is sent by the widget when the
254      * selection has changed.
255      * <p>
256      *
257      * @param selectionListener the listener
258      * @return <code>true</code> if adding a selection listener is supported
259      * <ul>
260      * <li>{@link org.eclipse.swt.SWT#ERROR_WIDGET_DISPOSED} - if the receiver has been disposed</li>
261      * <li>{@link org.eclipse.swt.SWT#ERROR_THREAD_INVALID_ACCESS} - if not called from the thread that created the receiver</li>
262      * </ul>
263      * @exception IllegalArgumentException if listener is <code>null</code>
264      */
265     boolean addSelectionListener(SelectionListener selectionListener);
266 }
267
Popular Tags