bundles/org.eclipse.ui.workbench/Eclipse UI/org/eclipse/ui/IViewPart.java

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


/**
 * A view is a visual component within a workbench page.  It is typically used to
 * navigate a hierarchy of information (like the workspace), open an editor,  
 * or display properties for the active editor.  Modifications made in a view are 
 * saved immediately (in contrast to an editor part, which conforms to a more 
 * elaborate open-save-close lifecycle).
 * <p>
 * Only one instance of a particular view type may exist within a workbench page.  
 * This policy is designed to simplify part management for a user.  
 * </p><p>
 * This interface may be implemented directly.  For convenience, a base
 * implementation is defined in <code>ViewPart</code>.
 * </p>
 * <p>
 * A view is added to the workbench in two steps:
 * <ol>
 * 	<li>A view extension is contributed to the workbench registry. This
 *    extension defines the extension id and extension class.</li>
 *  <li>The view is included in the default layout for a perspective.
 *    Alternatively, the user may open the view from the Perspective menu.</li>
 * </ol>
 * </p>
 * <p>
 * Views implement the <code>IAdaptable</code> interface; extensions
 * are managed by the platform's adapter manager.
 * </p>
 *
 * @see IWorkbenchPage#showView
 * @see org.eclipse.ui.part.ViewPart
 */
public interface IViewPart extends IWorkbenchPart, IPersistable {
    /**
     * Returns the site for this view. 
     * This method is equivalent to <code>(IViewSite) getSite()</code>.
     * <p>  
     * The site can be <code>null</code> while the view is being initialized. 
     * After the initialization is complete, this value must be non-<code>null</code>
     * for the remainder of the view's life cycle.
     * </p>
     * 
     * @return the view site; this value may be <code>null</code> if the view
     *         has not yet been initialized
     */
    public IViewSite getViewSite();

    /**
     * Initializes this view with the given view site.  
     * <p>
     * This method is automatically called by the workbench shortly after the
     * part is instantiated.  It marks the start of the views's lifecycle. Clients must 
     * not call this method.
     * </p>
     *
     * @param site the view site
     * @exception PartInitException if this view was not initialized successfully
     */
    public void init(IViewSite site) throws PartInitException;

    /**
     * Initializes this view with the given view site.  A memento is passed to
     * the view which contains a snapshot of the views state from a previous
     * session.  Where possible, the view should try to recreate that state
     * within the part controls.
     * <p>
     * This method is automatically called by the workbench shortly after the part 
     * is instantiated.  It marks the start of the views's lifecycle. Clients must 
     * not call this method.
     * </p>
     *
     * @param site the view site
     * @param memento the IViewPart state or null if there is no previous saved state
     * @exception PartInitException if this view was not initialized successfully
     */
    public void init(IViewSite site, IMemento memento) throws PartInitException;

    /**
     * Saves the object state within a memento.
     *
     * @param memento a memento to receive the object state
     */
    public void saveState(IMemento memento);
}