/*******************************************************************************
 * Copyright (c) 2006, 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.ui.dnd;

import org.eclipse.swt.dnd.DropTargetListener;
import org.eclipse.swt.dnd.Transfer;
import org.eclipse.swt.widgets.Control;

/**
 * This interface specifies the API for a service to be used by part authors to
 * access methods which provide support for Drag and Drop operations within the
 * workbench.
 * <p>
 * Authors should access this service using the PartSite's
 * <code>getService</code> method, passing this interface as the argument.
 * </p>
 * <p>
 * <b>NOTE:</b> This interface it not expected to be implemented by clients; it
 * is provided only to allow access to the service's methods.
 * </p>
 *
 * @since 3.3
 *
 */
public interface IDragAndDropService {
	/**
	 * Causes a drop target to be added to the given control that respects the
	 * existing site's drop behaviour in addition to the behaviour being specified
	 * for the given control.
	 * <p>
	 * If a transfer type specified for the control matches one used by the site
	 * then the control's listener is called (the client is overriding the existing
	 * site behaviour which will no longer work).
	 * </p>
	 * <p>
	 * NOTE: Site authors <b>must</b> use this method to add drop behaviour;
	 * directly adding drop targets using SWT onto a site will cause the standard
	 * site behaviour (i.e. dragging files / markers into the EditorSite...) to not
	 * work when that editor is active.
	 * </p>
	 * <p>
	 * Note that this method may be used more than once should the part author wish
	 * to register different drop targets for internal controls (i.e. to support
	 * internal DnD).
	 * </p>
	 *
	 * @param control   The control to add the drop behaviour to
	 * @param ops       The Drop operations used by this target
	 * @param transfers The TransferTypes used by this target
	 * @param listener  The listener controlling the target's behaviour
	 */
	void addMergedDropTarget(Control control, int ops, Transfer[] transfers, DropTargetListener listener);

	/**
	 * Remove any previously 'merged' drop target for this Control
	 *
	 * @param control The control to remove the drop target for
	 */
	void removeMergedDropTarget(Control control);
}
