/*******************************************************************************
 * Copyright (c) 2000, 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;

/**
 * An editor is a visual component within a workbench page. It is typically used
 * to edit or browse a document or input object. The input is identified using
 * an <code>IEditorInput</code>. Modifications made in an editor part follow an
 * open-save-close lifecycle model (in contrast to a view part, where
 * modifications are saved to the workbench immediately).
 * <p>
 * An editor is document or input-centric. Each editor has an input, and only
 * one editor can exist for each editor input within a page. This policy has
 * been designed to simplify part management.
 * </p>
 * <p>
 * An editor should be used in place of a view whenever more than one instance
 * of a document type can exist.
 * </p>
 * <p>
 * This interface may be implemented directly. For convenience, a base
 * implementation is defined in <code>EditorPart</code>.
 * </p>
 * <p>
 * An editor part is added to the workbench in two stages:
 * </p>
 * <ol>
 * <li>An editor extension is contributed to the workbench registry. This
 * extension defines the extension id, extension class, and the file extensions
 * which are supported by the editor.</li>
 * <li>An editor part based upon the extension is created and added to the
 * workbench when the user opens a file with one of the supported file
 * extensions (or some other suitable form of editor input).</li>
 * </ol>
 * <p>
 * All editor parts implement the <code>IAdaptable</code> interface; extensions
 * are managed by the platform's adapter manager.
 * </p>
 *
 * @see org.eclipse.ui.IWorkbenchPage#openEditor(IEditorInput, String)
 * @see org.eclipse.ui.part.EditorPart
 */
public interface IEditorPart extends IWorkbenchPart, ISaveablePart {

	/**
	 * The property id for <code>isDirty</code>.
	 */
	int PROP_DIRTY = IWorkbenchPartConstants.PROP_DIRTY;

	/**
	 * The property id for <code>getEditorInput</code>.
	 */
	int PROP_INPUT = IWorkbenchPartConstants.PROP_INPUT;

	/**
	 * Returns the input for this editor. If this value changes the part must fire a
	 * property listener event with <code>PROP_INPUT</code>.
	 *
	 * @return the editor input
	 */
	IEditorInput getEditorInput();

	/**
	 * Returns the site for this editor. This method is equivalent to
	 * <code>(IEditorSite) getSite()</code>.
	 * <p>
	 * The site can be <code>null</code> while the editor is being initialized.
	 * After the initialization is complete, this value must be
	 * non-<code>null</code> for the remainder of the editor's life cycle.
	 * </p>
	 *
	 * @return the editor site; this value may be <code>null</code> if the editor
	 *         has not yet been initialized
	 */
	IEditorSite getEditorSite();

	/**
	 * Initializes this editor with the given editor site and input.
	 * <p>
	 * This method is automatically called shortly after the part is instantiated.
	 * It marks the start of the part's lifecycle. The {@link IWorkbenchPart#dispose
	 * IWorkbenchPart.dispose} method will be called automically at the end of the
	 * lifecycle. Clients must not call this method.
	 * </p>
	 * <p>
	 * Implementors of this method must examine the editor input object type to
	 * determine if it is understood. If not, the implementor must throw a
	 * <code>PartInitException</code>
	 * </p>
	 *
	 * @param site  the editor site
	 * @param input the editor input
	 * @exception PartInitException if this editor was not initialized successfully
	 */
	void init(IEditorSite site, IEditorInput input) throws PartInitException;
}