001: /*******************************************************************************
002: * Copyright (c) 2000, 2006 IBM Corporation and others.
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * IBM Corporation - initial API and implementation
010: *******************************************************************************/package org.eclipse.ui;
011:
012: /**
013: * An editor is a visual component within a workbench page. It is
014: * typically used to edit or browse a document or input object. The input
015: * is identified using an <code>IEditorInput</code>. Modifications made
016: * in an editor part follow an open-save-close lifecycle model (in contrast
017: * to a view part, where modifications are saved to the workbench
018: * immediately).
019: * <p>
020: * An editor is document or input-centric. Each editor has an input, and only
021: * one editor can exist for each editor input within a page. This policy has
022: * been designed to simplify part management.
023: * </p><p>
024: * An editor should be used in place of a view whenever more than one instance
025: * of a document type can exist.
026: * </p><p>
027: * This interface may be implemented directly. For convenience, a base
028: * implementation is defined in <code>EditorPart</code>.
029: * </p>
030: * <p>
031: * An editor part is added to the workbench in two stages:
032: * <ol>
033: * <li>An editor extension is contributed to the workbench registry. This
034: * extension defines the extension id, extension class, and the file
035: * extensions which are supported by the editor.</li>
036: * <li>An editor part based upon the extension is created and added to the
037: * workbench when the user opens a file with one of the supported file
038: * extensions (or some other suitable form of editor input).</li>
039: * </ol>
040: * </p>
041: * <p>
042: * All editor parts implement the <code>IAdaptable</code> interface; extensions
043: * are managed by the platform's adapter manager.
044: * </p>
045: *
046: * @see org.eclipse.ui.IWorkbenchPage#openEditor(IEditorInput, String)
047: * @see org.eclipse.ui.part.EditorPart
048: */
049: public interface IEditorPart extends IWorkbenchPart, ISaveablePart {
050:
051: /**
052: * The property id for <code>isDirty</code>.
053: */
054: public static final int PROP_DIRTY = IWorkbenchPartConstants.PROP_DIRTY;
055:
056: /**
057: * The property id for <code>getEditorInput</code>.
058: */
059: public static final int PROP_INPUT = IWorkbenchPartConstants.PROP_INPUT;
060:
061: /**
062: * Returns the input for this editor. If this value changes the part must
063: * fire a property listener event with <code>PROP_INPUT</code>.
064: *
065: * @return the editor input
066: */
067: public IEditorInput getEditorInput();
068:
069: /**
070: * Returns the site for this editor.
071: * This method is equivalent to <code>(IEditorSite) getSite()</code>.
072: * <p>
073: * The site can be <code>null</code> while the editor is being initialized.
074: * After the initialization is complete, this value must be non-<code>null</code>
075: * for the remainder of the editor's life cycle.
076: * </p>
077: *
078: * @return the editor site; this value may be <code>null</code> if the editor
079: * has not yet been initialized
080: */
081: public IEditorSite getEditorSite();
082:
083: /**
084: * Initializes this editor with the given editor site and input.
085: * <p>
086: * This method is automatically called shortly after the part is instantiated.
087: * It marks the start of the part's lifecycle. The
088: * {@link IWorkbenchPart#dispose IWorkbenchPart.dispose} method will be called
089: * automically at the end of the lifecycle. Clients must not call this method.
090: * </p><p>
091: * Implementors of this method must examine the editor input object type to
092: * determine if it is understood. If not, the implementor must throw
093: * a <code>PartInitException</code>
094: * </p>
095: * @param site the editor site
096: * @param input the editor input
097: * @exception PartInitException if this editor was not initialized successfully
098: */
099: public void init(IEditorSite site, IEditorInput input)
100: throws PartInitException;
101: }
|