org.eclipse.jface.fieldassist.IControlContentAdapter.java Source code

Introduction

Here is the source code for org.eclipse.jface.fieldassist.IControlContentAdapter.java

Source

/*******************************************************************************
 * Copyright (c) 2005, 2015 IBM Corporation and others.
 *
 * This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License 2.0
 * which accompanies this distribution, and is available at
 * https://www.eclipse.org/legal/epl-2.0/
 *
 * SPDX-License-Identifier: EPL-2.0
 *
 * 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 <code>null</code>.
     *
     * @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 <code>null</code>.
     *
     * @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);
}