JFaceIInformationControlExtension5.java

/*******************************************************************************
 * Copyright (c) 2009 SpringSource, a divison of VMware, Inc.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 *     SpringSource, a division of VMware, Inc. - initial API and implementation
 *******************************************************************************/
package org.eclipse.virgo.ide.ui.editors.text;

import org.eclipse.jface.resource.JFaceResources;
import org.eclipse.jface.text.IInformationControl;
import org.eclipse.jface.text.IInformationControlCreator;
import org.eclipse.jface.text.IInformationControlExtension2;
import org.eclipse.jface.text.IInformationControlExtension3;
import org.eclipse.swt.SWT;
import org.eclipse.swt.graphics.Point;
import org.eclipse.swt.widgets.Control;

/**
 * Extension interface for {@link org.eclipse.jface.text.IInformationControl}.
 * Adds API
 * <ul>
 * <li>to test the visibility of the control,</li>
 * <li>to test whether another control is a child of the information control,</li>
 * <li>to compute size constraints based on the information control's main font
 * and</li>
 * <li>to return a control creator for an enriched version of this information
 * control.</li>
 * </ul>
 * <p>
 * <b>Important:</b> Enriching this information control only works properly if
 * {@link IInformationControl#isFocusControl()} is implemented like this (
 * <code>fShell</code> is the control's shell):
 * <pre>
 * return fShell.getDisplay().getActiveShell() == fShell
 * </pre>
 * Likewise,
 * {@link IInformationControl#addFocusListener(org.eclipse.swt.events.FocusListener)}should install listeners for {@link SWT#Activate} and {@link SWT#Deactivate}on the shell and forward events to the focus listeners. Clients are
 * encouraged to subclass {@link AbstractInformationControl}, which does this
 * for free.
 * </p>
 * @author Christian Dupuis
 * @see org.eclipse.jface.text.IInformationControl
 * @since 3.4
 */
public interface JFaceIInformationControlExtension5 {

	/**
	 * Tests whether the given control is this information control or a child of
	 * this information control.
	 * 
	 * @param control the control to test
	 * @return <code>true</code> iff the given control is this information
	 * control or a child of this information control
	 */
	public boolean containsControl(Control control);

	/**
	 * @return <code>true</code> iff the information control is currently
	 * visible
	 */
	public abstract boolean isVisible();

	/**
	 * Computes the width- and height constraints of the information control in
	 * pixels, based on the given width and height in characters. Implementors
	 * should use the main font of the information control to do the
	 * characters-to-pixels conversion. This is typically the
	 * {@link JFaceResources#getDialogFont() dialog font}.
	 * 
	 * @param widthInChars the width constraint in number of characters
	 * @param heightInChars the height constraint in number of characters
	 * @return a point with width and height in pixels, or <code>null</code> to
	 * use the subject control's font to calculate the size
	 */
	public Point computeSizeConstraints(int widthInChars, int heightInChars);

	/**
	 * Returns the rich information control creator for this information
	 * control.
	 * <p>
	 * The returned information control creator is used to create an enriched
	 * version of this information control, e.g. when the mouse is moved into
	 * this control and it needs to be enriched} or when it needs to be made
	 * sticky for other reasons.
	 * </p>
	 * <p>
	 * The returned information control creator must create information controls
	 * that implement {@link IInformationControlExtension3} and
	 * {@link IInformationControlExtension2}, and whose
	 * {@link IInformationControlExtension2#setInput(Object)} accepts all inputs
	 * that are also supported by this information control.
	 * </p>
	 * <p>
	 * Note that automatic enriching of this information control works only if
	 * it also implements {@link IInformationControlExtension3}.
	 * </p>
	 * <p>
	 * This method may be called frequently, so implementors should ensure it
	 * returns quickly, e.g. by caching the returned creator.
	 * </p>
	 * 
	 * @return the information presenter control creator or <code>null</code> to
	 * disable enriching
	 */
	IInformationControlCreator getInformationPresenterControlCreator();

}