org.eclipse.jface.fieldassist.IControlContentAdapter Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of org.eclipse.jface Show documentation
This is org.eclipse.jface jar used by Scout SDK
The newest version!
/*******************************************************************************
 * Copyright (c) 2005, 2015 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.fieldassist;

import org.eclipse.swt.graphics.Rectangle;
import org.eclipse.swt.widgets.Control;

/**
 * This interface is used to set and retrieve text content from an arbitrary
 * control. Clients are expected to implement this interface when defining a
 * {@link ContentProposalAdapter}, in order to specify how to retrieve and set
 * the contents of the control being adapted.
 *
 * @since 3.2
 */
public interface IControlContentAdapter {
	/**
	 * Set the contents of the specified control to the specified text. Must not
	 * be null.
	 *
	 * @param control
	 *            the control whose contents are to be set (replaced).
	 * @param contents
	 *            the String specifying the new control content.
	 * @param cursorPosition
	 *            the zero-based index representing the desired cursor position
	 *            in the control's contents after the contents are set.
	 */
	public void setControlContents(Control control, String contents,
			int cursorPosition);

	/**
	 * Insert the specified contents into the control's current contents. Must
	 * not be null.
	 *
	 * @param control
	 *            the control whose contents are to be altered.
	 * @param contents
	 *            the String to be inserted into the control contents.
	 * @param cursorPosition
	 *            the zero-based index representing the desired cursor position
	 *            within the inserted contents after the insertion is made.
	 */
	public void insertControlContents(Control control, String contents,
			int cursorPosition);

	/**
	 * Get the text contents of the control.
	 *
	 * @param control
	 *            the control whose contents are to be retrieved.
	 * @return the String contents of the control.
	 */
	public String getControlContents(Control control);

	/**
	 * Get the current cursor position in the control. The position is specified
	 * as a zero-based index into the string. Valid ranges are from 0 to N,
	 * where N is the size of the contents string. A value of N indicates that
	 * the cursor is at the end of the contents.
	 *
	 * @param control
	 *            the control whose position is to be retrieved.
	 * @return the zero-based index representing the cursor position in the
	 *         control's contents.
	 */
	public int getCursorPosition(Control control);

	/**
	 * Get the bounds (in pixels) of the insertion point for the control
	 * content. This is a rectangle, in coordinates relative to the control,
	 * where the insertion point is displayed. If the implementer does not have
	 * an insertion point, or cannot determine the location of the insertion
	 * point, it is appropriate to return the bounds of the entire control. This
	 * value may be used to position a content proposal popup.
	 *
	 * @param control
	 *            the control whose offset is to be retrieved.
	 * @return the pixel width representing the distance between the edge of the
	 *         control and the insertion point.
	 */
	public Rectangle getInsertionBounds(Control control);

	/**
	 * Set the current cursor position in the control. The position is specified
	 * as a zero-based index into the string. Valid ranges are from 0 to N,
	 * where N is the size of the contents string. A value of N indicates that
	 * the cursor is at the end of the contents.
	 *
	 * @param control
	 *            the control whose cursor position is to be set.
	 * @param index
	 *            the zero-based index representing the cursor position in the
	 *            control's contents.
	 */
	public void setCursorPosition(Control control, int index);
}