org.eclipse.jface.text.IInformationControlExtension5 Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of org.eclipse.jface.text Show documentation
This is org.eclipse.jface.text jar used by Scout SDK
The newest version!
/*******************************************************************************
 * Copyright (c) 2008 IBM Corporation and others.
 * 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:
 *     IBM Corporation - initial API and implementation
 *******************************************************************************/
package org.eclipse.jface.text;

import org.eclipse.swt.SWT;
import org.eclipse.swt.graphics.Point;
import org.eclipse.swt.widgets.Control;

import org.eclipse.jface.resource.JFaceResources;


/**
 * Extension interface for {@link org.eclipse.jface.text.IInformationControl}.
 * Adds API
 * 
 * to test the visibility of the control,
 * to test whether another control is a child of the information control,
 * to compute size constraints based on the information control's main font and
 * to return a control creator for an enriched version of this information control.
 * 
 *
 * 
 * Important: Enriching this information control only works properly if
 * {@link IInformationControl#isFocusControl()} is implemented like this (fShell
 * is the control's shell):
 *
 * 
 * return fShell.getDisplay().getActiveShell() == fShell
 * 
 * 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.
 * 
 *
 * @see org.eclipse.jface.text.IInformationControl
 * @since 3.4
 */
public interface IInformationControlExtension5 {

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

	/**
	 * @return true 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 null
	 *         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.
	 * 
	 * 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
	 * {@link ITextViewerExtension8#setHoverEnrichMode(org.eclipse.jface.text.ITextViewerExtension8.EnrichMode) enriched}
	 * or when it needs to be made sticky for other reasons.
	 * 
	 * 
	 * 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.
	 * 
	 * 
	 * Note that automatic enriching of this information control works only if it also implements
	 * {@link IInformationControlExtension3}.
	 * 
	 * 
	 * This method may be called frequently, so implementors should ensure it returns quickly,
	 * e.g. by caching the returned creator.
	 * 
	 *
	 * @return the information presenter control creator or null to disable enriching
	 */
	IInformationControlCreator getInformationPresenterControlCreator();

}