001: /*******************************************************************************
002: * Copyright (c) 2000, 2007 IBM Corporation and others.
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * IBM Corporation - initial API and implementation
010: *******************************************************************************/package org.eclipse.jface.text;
011:
012: import org.eclipse.swt.events.DisposeListener;
013: import org.eclipse.swt.events.FocusListener;
014: import org.eclipse.swt.graphics.Color;
015: import org.eclipse.swt.graphics.Point;
016:
017: /**
018: * Interface of a control presenting information. The information is given in
019: * the form of an input object. It can be either the content itself or a
020: * description of the content. The specification of what is required from an
021: * input object is left to the implementers of this interface.
022: * <p>
023: * <em>If this information control is used by a {@link AbstractHoverInformationControlManager}
024: * then that manager will own this control and override any properties that
025: * may have been set before by any other client.</em></p>
026: * <p>
027: * The information control may not grab focus when made visible using
028: * <code>setVisible(true)</code>.
029: *
030: * In order to provide backward compatibility for clients of
031: * <code>IInformationControl</code>, extension interfaces are used as a means
032: * of evolution. The following extension interfaces exist:
033: * <ul>
034: * <li>{@link org.eclipse.jface.text.IInformationControlExtension} since
035: * version 2.0 introducing the predicate of whether the control has anything to
036: * show or would be empty</li>
037: * <li>{@link org.eclipse.jface.text.IInformationControlExtension2} since
038: * version 2.1 replacing the original concept of textual input by general input
039: * objects.</li>
040: * <li>{@link org.eclipse.jface.text.IInformationControlExtension3} since
041: * version 3.0 providing access to the control's bounds and introducing
042: * the concept of persistent size and location.</li>
043: * <li>{@link org.eclipse.jface.text.IInformationControlExtension4} since
044: * version 3.3, adding API which allows to set this information control's status field text.</li>
045: * </ul>
046: * <p>
047: * Clients can implements that interface and its extension interfaces or use the
048: * provided default implementation {@link org.eclipse.jface.text.DefaultInformationControl}.
049: *
050: * @see org.eclipse.jface.text.IInformationControlExtension
051: * @see org.eclipse.jface.text.IInformationControlExtension2
052: * @see org.eclipse.jface.text.IInformationControlExtension3
053: * @see org.eclipse.jface.text.IInformationControlExtension4
054: * @since 2.0
055: */
056: public interface IInformationControl {
057:
058: /**
059: * Sets the information to be presented by this information control.
060: * <p>
061: * Replaced by {@link IInformationControlExtension2#setInput(Object)}.
062: *
063: * @param information the information to be presented
064: */
065: void setInformation(String information);
066:
067: /**
068: * Sets the information control's size constraints. A constraint value of
069: * <code>-1</code> indicates no constraint. This method must be called before
070: * <code>computeSizeHint</code> is called.
071: * <p>
072: * Note: An information control which implements {@link IInformationControlExtension3}
073: * may ignore this method or use it as hint for its very first appearance.
074: * </p>
075: * @param maxWidth the maximal width of the control to present the information, or <code>-1</code> for not constraint
076: * @param maxHeight the maximal height of the control to present the information, or <code>-1</code> for not constraint
077: */
078: void setSizeConstraints(int maxWidth, int maxHeight);
079:
080: /**
081: * Computes and returns a proposal for the size of this information control depending
082: * on the information to present. The method tries to honor known size constraints but might
083: * return a size that exceeds them.
084: *
085: * @return the computed size hint
086: */
087: Point computeSizeHint();
088:
089: /**
090: * Controls the visibility of this information control.
091: *
092: * @param visible <code>true</code> if the control should be visible
093: */
094: void setVisible(boolean visible);
095:
096: /**
097: * Sets the size of this information control.
098: *
099: * @param width the width of the control
100: * @param height the height of the control
101: */
102: void setSize(int width, int height);
103:
104: /**
105: * Sets the location of this information control.
106: *
107: * @param location the location
108: */
109: void setLocation(Point location);
110:
111: /**
112: * Disposes this information control.
113: */
114: void dispose();
115:
116: /**
117: * Adds the given listener to the list of dispose listeners.
118: * If the listener is already registered it is not registered again.
119: *
120: * @param listener the listener to be added
121: */
122: void addDisposeListener(DisposeListener listener);
123:
124: /**
125: * Removes the given listeners from the list of dispose listeners.
126: * If the listener is not registered this call has no effect.
127: *
128: * @param listener the listener to be removed
129: */
130: void removeDisposeListener(DisposeListener listener);
131:
132: /**
133: * Sets the foreground color of this information control.
134: *
135: * @param foreground the foreground color of this information control
136: */
137: void setForegroundColor(Color foreground);
138:
139: /**
140: * Sets the background color of this information control.
141: *
142: * @param background the background color of this information control
143: */
144: void setBackgroundColor(Color background);
145:
146: /**
147: * Returns whether this information control has the focus.
148: *
149: * @return <code>true</code> when the information control has the focus otherwise <code>false</code>
150: */
151: boolean isFocusControl();
152:
153: /**
154: * Sets the keyboard focus to this information control.
155: */
156: void setFocus();
157:
158: /**
159: * Adds the given listener to the list of focus listeners.
160: * If the listener is already registered it is not registered again.
161: *
162: * @param listener the listener to be added
163: */
164: void addFocusListener(FocusListener listener);
165:
166: /**
167: * Removes the given listeners from the list of focus listeners.
168: * If the listener is not registered this call has no affect.
169: *
170: * @param listener the listener to be removed
171: */
172: void removeFocusListener(FocusListener listener);
173: }
|