1 /******************************************************************************* 2 * Copyright (c) 2008 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.graphics.Point; 18 import org.eclipse.swt.widgets.Control; 19 20 import org.eclipse.jface.resource.JFaceResources; 21 22 23 /** 24 * Extension interface for {@link org.eclipse.jface.text.IInformationControl}. Adds API 25 * <ul> 26 * <li>to test the visibility of the control,</li> 27 * <li>to test whether another control is a child of the information control,</li> 28 * <li>to compute size constraints based on the information control's main font and</li> 29 * <li>to return a control creator for an enriched version of this information control.</li> 30 * </ul> 31 * 32 * <p> 33 * <b>Important:</b> Enriching this information control only works properly if 34 * {@link IInformationControl#isFocusControl()} is implemented like this (<code>fShell</code> is the 35 * control's shell): 36 * </p> 37 * 38 * <pre> 39 * return fShell.getDisplay().getActiveShell() == fShell 40 * </pre> 41 * 42 * Likewise, {@link IInformationControl#addFocusListener(org.eclipse.swt.events.FocusListener)} 43 * should install listeners for {@link SWT#Activate} and {@link SWT#Deactivate} on the shell and 44 * forward events to the focus listeners. Clients are encouraged to subclass 45 * {@link AbstractInformationControl}, which does this for free. 46 * 47 * @see org.eclipse.jface.text.IInformationControl 48 * @since 3.4 49 */ 50 public interface IInformationControlExtension5 { 51 52 /** 53 * Tests whether the given control is this information control 54 * or a child of this information control. 55 * 56 * @param control the control to test 57 * @return <code>true</code> iff the given control is this information control 58 * or a child of this information control 59 */ containsControl(Control control)60 public boolean containsControl(Control control); 61 62 /** 63 * @return <code>true</code> iff the information control is currently visible 64 */ isVisible()65 public abstract boolean isVisible(); 66 67 /** 68 * Computes the width- and height constraints of the information control in 69 * pixels, based on the given width and height in characters. Implementors 70 * should use the main font of the information control to do the 71 * characters-to-pixels conversion. This is typically the 72 * {@link JFaceResources#getDialogFont() dialog font}. 73 * 74 * @param widthInChars the width constraint in number of characters 75 * @param heightInChars the height constraint in number of characters 76 * @return a point with width and height in pixels, or <code>null</code> 77 * to use the subject control's font to calculate the size 78 */ computeSizeConstraints(int widthInChars, int heightInChars)79 public Point computeSizeConstraints(int widthInChars, int heightInChars); 80 81 /** 82 * Returns the rich information control creator for this information control. 83 * <p> 84 * The returned information control creator is used to create an enriched version of this 85 * information control, e.g. when the mouse is moved into this control and it needs to be 86 * {@link ITextViewerExtension8#setHoverEnrichMode(org.eclipse.jface.text.ITextViewerExtension8.EnrichMode) enriched} 87 * or when it needs to be made sticky for other reasons. 88 * </p> 89 * <p> 90 * The returned information control creator must create information controls 91 * that implement {@link IInformationControlExtension3} and {@link IInformationControlExtension2}, 92 * and whose {@link IInformationControlExtension2#setInput(Object)} accepts all inputs that are 93 * also supported by this information control. 94 * </p> 95 * <p> 96 * Note that automatic enriching of this information control works only if it also implements 97 * {@link IInformationControlExtension3}. 98 * </p> 99 * <p> 100 * This method may be called frequently, so implementors should ensure it returns quickly, 101 * e.g. by caching the returned creator. 102 * </p> 103 * 104 * @return the information presenter control creator or <code>null</code> to disable enriching 105 */ getInformationPresenterControlCreator()106 IInformationControlCreator getInformationPresenterControlCreator(); 107 108 } 109