01: /*******************************************************************************
02: * Copyright (c) 2000, 2006 IBM Corporation and others.
03: * All rights reserved. This program and the accompanying materials
04: * are made available under the terms of the Eclipse Public License v1.0
05: * which accompanies this distribution, and is available at
06: * http://www.eclipse.org/legal/epl-v10.html
07: *
08: * Contributors:
09: * IBM Corporation - initial API and implementation
10: *******************************************************************************/package org.eclipse.jface.text;
11:
12: /**
13: * A widget token keeper may require a widget token from an
14: * {@link org.eclipse.jface.text.IWidgetTokenOwner} and release the token to the
15: * owner after usage. A widget token owner may request the token from the token
16: * keeper. The keeper may deny the return of the token.
17: * <p>
18: * The widget token owner and keeper interplay is used by a text viewer in
19: * order to manage the appearance and disappearance of addition, on-top popup
20: * windows such as text hovers, content assist, etc.
21: *
22: * In order to provide backward compatibility for clients of
23: * <code>IWidgetTokeKeeper</code>, extension interfaces are used as a means
24: * of evolution. The following extension interfaces exist:
25: * <ul>
26: * <li>{@link org.eclipse.jface.text.IWidgetTokenKeeperExtension} since version
27: * 3.0 introducing priorities when requesting a widget token and thus replacing
28: * the non-prioritized scheme. It also allows a client to force a widget token
29: * keeper to accept focus.</li>
30: * </ul>
31: *
32: * @see org.eclipse.jface.text.IWidgetTokenKeeperExtension
33: * @since 2.0
34: */
35: public interface IWidgetTokenKeeper {
36:
37: /**
38: * The given widget token owner requests the widget token from this token
39: * keeper. Returns <code>true</code> if the token is released by this
40: * token keeper. Note, the keeper must not call
41: * <code>releaseWidgetToken(IWidgetTokenKeeper)</code> explicitly.
42: * <p>
43: * Replaced by
44: * {@link IWidgetTokenKeeperExtension#requestWidgetToken(IWidgetTokenOwner, int)}.
45: *
46: * @param owner the token owner
47: * @return <code>true</code> if token has been released <code>false</code>
48: * otherwise
49: */
50: boolean requestWidgetToken(IWidgetTokenOwner owner);
51: }
|