1 /******************************************************************************* 2 * Copyright (c) 2000, 2010 IBM Corporation and others. 3 * 4 * This program and the accompanying materials 5 * are made available under the terms of the Eclipse Public License 2.0 6 * which accompanies this distribution, and is available at 7 * https://www.eclipse.org/legal/epl-2.0/ 8 * 9 * SPDX-License-Identifier: EPL-2.0 10 * 11 * Contributors: 12 * IBM Corporation - initial API and implementation 13 *******************************************************************************/ 14 package org.eclipse.jface.text; 15 16 import org.eclipse.swt.SWT; 17 import org.eclipse.swt.events.DisposeListener; 18 import org.eclipse.swt.events.FocusListener; 19 import org.eclipse.swt.graphics.Color; 20 import org.eclipse.swt.graphics.Point; 21 22 23 /** 24 * Interface of a control presenting information. The information is given in 25 * the form of an input object. It can be either the content itself or a 26 * description of the content. The specification of what is required from an 27 * input object is left to the implementers of this interface. 28 * <p> 29 * <em>If this information control is used by a {@link AbstractHoverInformationControlManager} 30 * then that manager will own this control and override any properties that 31 * may have been set before by any other client.</em></p> 32 * <p> 33 * The information control must not grab focus when made visible using 34 * <code>setVisible(true)</code>. 35 * 36 * In order to provide backward compatibility for clients of 37 * <code>IInformationControl</code>, extension interfaces are used as a means 38 * of evolution. The following extension interfaces exist: 39 * <ul> 40 * <li>{@link org.eclipse.jface.text.IInformationControlExtension} since 41 * version 2.0 introducing the predicate of whether the control has anything to 42 * show or would be empty</li> 43 * <li>{@link org.eclipse.jface.text.IInformationControlExtension2} since 44 * version 2.1 replacing the original concept of textual input by general input 45 * objects.</li> 46 * <li>{@link org.eclipse.jface.text.IInformationControlExtension3} since 47 * version 3.0 providing access to the control's bounds and introducing 48 * the concept of persistent size and location.</li> 49 * <li>{@link org.eclipse.jface.text.IInformationControlExtension4} since 50 * version 3.3, adding API which allows to set this information control's status field text.</li> 51 * <li>{@link org.eclipse.jface.text.IInformationControlExtension5} since 52 * version 3.4, adding API to get the visibility of the control, to 53 * test whether another control is a child of the information control, 54 * to compute size constraints based on the information control's main font 55 * and to return a control creator for an enriched version of this information control.</li> 56 * </ul> 57 * <p> 58 * Clients can implement this interface and its extension interfaces, 59 * subclass {@link AbstractInformationControl}, or use the (text-based) 60 * default implementation {@link DefaultInformationControl}. 61 * 62 * @see org.eclipse.jface.text.IInformationControlExtension 63 * @see org.eclipse.jface.text.IInformationControlExtension2 64 * @see org.eclipse.jface.text.IInformationControlExtension3 65 * @see org.eclipse.jface.text.IInformationControlExtension4 66 * @see org.eclipse.jface.text.IInformationControlExtension5 67 * @see AbstractInformationControl 68 * @see DefaultInformationControl 69 * @since 2.0 70 */ 71 public interface IInformationControl { 72 73 /** 74 * Sets the information to be presented by this information control. 75 * <p> 76 * Replaced by {@link IInformationControlExtension2#setInput(Object)}. 77 * 78 * @param information the information to be presented 79 */ setInformation(String information)80 void setInformation(String information); 81 82 /** 83 * Sets the information control's size constraints. A constraint value of 84 * {@link SWT#DEFAULT} indicates no constraint. This method must be called before 85 * {@link #computeSizeHint()} is called. 86 * <p> 87 * Note: An information control which implements {@link IInformationControlExtension3} 88 * may ignore this method or use it as hint for its very first appearance. 89 * </p> 90 * @param maxWidth the maximal width of the control to present the information, or {@link SWT#DEFAULT} for not constraint 91 * @param maxHeight the maximal height of the control to present the information, or {@link SWT#DEFAULT} for not constraint 92 */ setSizeConstraints(int maxWidth, int maxHeight)93 void setSizeConstraints(int maxWidth, int maxHeight); 94 95 /** 96 * Computes and returns a proposal for the size of this information control depending 97 * on the information to present. The method tries to honor known size constraints but might 98 * return a size that exceeds them. 99 * 100 * @return the computed size hint 101 */ computeSizeHint()102 Point computeSizeHint(); 103 104 /** 105 * Controls the visibility of this information control. 106 * <p> 107 * <strong>Note:</strong> The information control must not grab focus when 108 * made visible. 109 * </p> 110 * 111 * @param visible <code>true</code> if the control should be visible 112 */ setVisible(boolean visible)113 void setVisible(boolean visible); 114 115 /** 116 * Sets the size of this information control. 117 * 118 * @param width the width of the control 119 * @param height the height of the control 120 */ setSize(int width, int height)121 void setSize(int width, int height); 122 123 /** 124 * Sets the location of this information control. 125 * 126 * @param location the location 127 */ setLocation(Point location)128 void setLocation(Point location); 129 130 /** 131 * Disposes this information control. 132 */ dispose()133 void dispose(); 134 135 /** 136 * Adds the given listener to the list of dispose listeners. 137 * If the listener is already registered it is not registered again. 138 * 139 * @param listener the listener to be added 140 */ addDisposeListener(DisposeListener listener)141 void addDisposeListener(DisposeListener listener); 142 143 /** 144 * Removes the given listeners from the list of dispose listeners. 145 * If the listener is not registered this call has no effect. 146 * 147 * @param listener the listener to be removed 148 */ removeDisposeListener(DisposeListener listener)149 void removeDisposeListener(DisposeListener listener); 150 151 /** 152 * Sets the foreground color of this information control. 153 * 154 * @param foreground the foreground color of this information control 155 */ setForegroundColor(Color foreground)156 void setForegroundColor(Color foreground); 157 158 /** 159 * Sets the background color of this information control. 160 * 161 * @param background the background color of this information control 162 */ setBackgroundColor(Color background)163 void setBackgroundColor(Color background); 164 165 /** 166 * Returns whether this information control (or one of its children) has the focus. 167 * The suggested implementation is like this (<code>fShell</code> is this information control's shell): 168 * <pre>return fShell.getDisplay().getActiveShell() == fShell</pre> 169 * 170 * <p>Note that implementations of {@link IInformationControlExtension5} are required to use this 171 * suggested implementation. 172 * </p> 173 * 174 * @return <code>true</code> when the information control has the focus, otherwise <code>false</code> 175 */ isFocusControl()176 boolean isFocusControl(); 177 178 /** 179 * Sets the keyboard focus to this information control. 180 */ setFocus()181 void setFocus(); 182 183 /** 184 * Adds the given listener to the list of focus listeners. 185 * If the listener is already registered it is not registered again. 186 * <p> 187 * The suggested implementation is to install listeners for {@link SWT#Activate} and {@link SWT#Deactivate} 188 * on the shell and forward events to the focus listeners. Clients are 189 * encouraged to subclass {@link AbstractInformationControl}, which does this 190 * for free. 191 * </p> 192 * 193 * @param listener the listener to be added 194 */ addFocusListener(FocusListener listener)195 void addFocusListener(FocusListener listener); 196 197 /** 198 * Removes the given listeners from the list of focus listeners. 199 * If the listener is not registered this call has no effect. 200 * 201 * @param listener the listener to be removed 202 */ removeFocusListener(FocusListener listener)203 void removeFocusListener(FocusListener listener); 204 } 205