/*******************************************************************************
 * Copyright (c) 2000, 2007 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>
 * <p>
 * As of 1.1, views may optionally adapt to {@link ISizeProvider} if they have
 * a preferred size. The default presentation will make a best effort to
 * allocate the preferred size to a view if it is the only part in a stack. If
 * there is more than one part in the stack, the constraints will be disabled
 * for that stack. The size constraints are adjusted for the size of the tab and
 * border trim. Note that this is considered to be a hint to the presentation,
 * and not all presentations may honor size constraints.
 * </p>
 * 
 * @since 1.0
 * @see IWorkbenchPage#showView
 * @see org.eclipse.ui.part.ViewPart
 * @see ISizeProvider
 */
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);
}