001: /*******************************************************************************
002: * Copyright (c) 2000, 2005 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: * A view is a visual component within a workbench page. It is typically used to
014: * navigate a hierarchy of information (like the workspace), open an editor, or
015: * display properties for the active editor. Modifications made in a view are
016: * saved immediately (in contrast to an editor part, which conforms to a more
017: * elaborate open-save-close lifecycle).
018: * <p>
019: * Only one instance of a particular view type may exist within a workbench
020: * page. This policy is designed to simplify part management for a user.
021: * </p>
022: * <p>
023: * This interface may be implemented directly. For convenience, a base
024: * implementation is defined in <code>ViewPart</code>.
025: * </p>
026: * <p>
027: * A view is added to the workbench in two steps:
028: * <ol>
029: * <li>A view extension is contributed to the workbench registry. This
030: * extension defines the extension id and extension class.</li>
031: * <li>The view is included in the default layout for a perspective.
032: * Alternatively, the user may open the view from the Perspective menu.</li>
033: * </ol>
034: * </p>
035: * <p>
036: * Views implement the <code>IAdaptable</code> interface; extensions are
037: * managed by the platform's adapter manager.
038: * </p>
039: * <p>
040: * As of 3.4, views may optionally adapt to {@link ISizeProvider} if they have
041: * a preferred size. The default presentation will make a best effort to
042: * allocate the preferred size to a view if it is the only part in a stack. If
043: * there is more than one part in the stack, the constraints will be disabled
044: * for that stack. The size constraints are adjusted for the size of the tab and
045: * border trim. Note that this is considered to be a hint to the presentation,
046: * and not all presentations may honor size constraints.
047: * </p>
048: *
049: * @see IWorkbenchPage#showView
050: * @see org.eclipse.ui.part.ViewPart
051: * @see ISizeProvider
052: */
053: public interface IViewPart extends IWorkbenchPart, IPersistable {
054: /**
055: * Returns the site for this view.
056: * This method is equivalent to <code>(IViewSite) getSite()</code>.
057: * <p>
058: * The site can be <code>null</code> while the view is being initialized.
059: * After the initialization is complete, this value must be non-<code>null</code>
060: * for the remainder of the view's life cycle.
061: * </p>
062: *
063: * @return the view site; this value may be <code>null</code> if the view
064: * has not yet been initialized
065: */
066: public IViewSite getViewSite();
067:
068: /**
069: * Initializes this view with the given view site.
070: * <p>
071: * This method is automatically called by the workbench shortly after the
072: * part is instantiated. It marks the start of the views's lifecycle. Clients must
073: * not call this method.
074: * </p>
075: *
076: * @param site the view site
077: * @exception PartInitException if this view was not initialized successfully
078: */
079: public void init(IViewSite site) throws PartInitException;
080:
081: /**
082: * Initializes this view with the given view site. A memento is passed to
083: * the view which contains a snapshot of the views state from a previous
084: * session. Where possible, the view should try to recreate that state
085: * within the part controls.
086: * <p>
087: * This method is automatically called by the workbench shortly after the part
088: * is instantiated. It marks the start of the views's lifecycle. Clients must
089: * not call this method.
090: * </p>
091: *
092: * @param site the view site
093: * @param memento the IViewPart state or null if there is no previous saved state
094: * @exception PartInitException if this view was not initialized successfully
095: */
096: public void init(IViewSite site, IMemento memento)
097: throws PartInitException;
098:
099: /**
100: * Saves the object state within a memento.
101: *
102: * @param memento a memento to receive the object state
103: */
104: public void saveState(IMemento memento);
105: }
|